CHAPTER 


Tcl/Tk Features 


Your first question is likely to be “What features will Tcl/Tk offer me that other languages won’t?” 
This chapter gives you an overview of the Tcl/Tk features. It covers the basics of what Tcl/Tk can offer 
you and what its strengths are compared with several alternatives. 

Tcl is a multifaceted language package. You can use Tcl as a command scripting language, as a 
powerful multi-platform interpreted language, as a rapid prototyping platform, or as the backbone of 
an application that is primarily written in C or Java. You can use the Tcl and Tk libraries to embed 
powerful scripting capabilities into a compiled application like C, Java or FORTRAN. Tcl’s simple 
syntax makes single-use scripts (to replace repetitive command typing or graphical user interface (GUI) 
clicking) quick and easy to write. Tcl’s modularization, encapsulation and object oriented features help 
you develop large (100,000 + lines of code) projects. Tcl’s extensibility makes it easy to use Tcl as 
the base language across a broad range of projects, from machine control to database applications to 
electronic design applications, network test devices, and more. 

Tcl is both free software and a commercially supported package. The core Tcl language is pri- 
marily supported by a worldwide group of volunteers. Commercial support can be purchased from 
ActiveState, Noumena Corporation, Cygnus Solutions, and others. 

The central site for Tcl/Tk information is http://www.tcl.tk. The source code reposi- 
tory and some binary snapshots are maintained at http://sourceforge.net/projects/tcl/. 
Tcl/Tk runtime packages are included with the Linux and FreeBSD packages, and with commer- 
cial UNIX distributions such as Solaris, HPUX and Mac OS X. The current binaries for selected 
systems (including MS-Windows, Linux, Mac OS X, and Solaris) are available from ActiveState 
(http: //www.activestate.com). 

One of the strengths of Tcl is the number of special-purpose extensions that have been added to the 
language. Extensions are commonly written in “C” and add high-performance special purpose features 
that not all users need to the language. The use of extensions keeps the Tcl base language small, while 
supporting a wide variety of uses. 

The most popular Tcl extension is Tk, which stands for Tool Kit. This extension provides tools for 
graphics programming, including drawing canvases, buttons, menus, and so on. The Tk extension is 
considered part of the Tcl core and is included in the source code distributions at Sourceforge and most 
binary distributions. 

Other popular extensions to Tcl include [incr Tcl] (which adds support for C++ style object- 
oriented programming to Tcl) and expect, an extension that simplifies controlling other applications 
and devices and allows many complex tasks to be easily automated. 
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With Tcl 8.6 (released in 2010) object-oriented support is part of the core language. The Tcl-OO 
support provides object-oriented features that mimic smalltalk, Objective-C and C++. Tcl-OO is a 
powerful programming tool, and can be used to create pure Tcl extensions like [incr Tcl] and 
XOTc1. Creating these language extensions in pure Tcl, without any compiled code, assures that the 
extension will run on any platform that the Tcl interpreter can be built for. 

Many extensions including expect (for controlling remote systems and routers), TclX (with 
commands for systems administration), Img and crimp (for image processing) are available both 
as source code and in binary format. Links to these resources are available from the companion 
website by visiting: http://www.elsevierdirect.com/9780123847171. 

Dr. John Ousterhout received the 1997 Software System Award from the Association for Com- 
puting Machinery (ACM) for inventing Tcl/Tk. This award recognizes the development of a software 
system that has a lasting influence. The ACM press release says it well. 


The Tcl scripting language and its companion Tk user interface toolkit have proved to be a powerful 
combination. Tcl is widely used as the glue that allows developers to create complex systems using 
preexisting systems as their components. As one of the first embeddable scripting languages, Tcl 
has revolutionized the creation of customizable and extensible applications. Tk provides a much 
simpler mechanism to construct graphical user interfaces than traditional programming languages. 
The overall Tcl/Tk system has had substantial impact through its wide use in the developer community 
and thousands of successful commercial applications. 


1.1 TCL OVERVIEW 


Tcl (pronounced either as the three letters, or as “tickle”) stands for Tool Command Language. 
This name reflects Tcl’s strength as a scripting language for gluing other applications together into 
a new application. 

Tcl was developed by Dr. John Ousterhout while he was at the University of California at Berkeley. 
He and his group developed simulation packages that needed macro languages to control them. After 
creating a few on-the-fly languages that were tailored to one application and would not work for 
another, they decided to create an interpreter library they could merge into the other projects. This pro- 
vided a common parsing package that could be used with each project, and a common base language 
across the applications. 

The original design goal for Tcl was to create a language that could be embedded in other programs 
and easily extended with new functionality. Tcl was also designed to execute other programs in the 
manner of a shell scripting language. By placing a small wrapper around the Tcl library, Dr. Ousterhout 
and his group created tclsh, a program that could be used as an interactive shell and as a script 
interpreter. 

Dr. Ousterhout expected that this solid base for building specialized languages around a common set 
of core commands and syntax would be useful for building specialized tools. However, as programmers 
created Tcl extensions with support for graphics, database interaction, distributed processing, and so 
on, they also started writing applications in pure Tcl. In fact, the Tcl language turned out to be powerful 
enough that many programs can be written using tcl sh as an interpreter with no extensions. 
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Today, Tcl is widely used for in-house packages, as an embedded scripting language in commercial 
products, as a rapid prototyping language, as a framework for regression testing, and for 24/7 mission- 
critical applications. The robustness of the Tcl interpreter is demonstrated by such mission-critical 
applications as controlling offshore oil platforms, product Q/A and Q/C operations, and running the 
NBC broadcasting studios. Many companies are open about their use of Tcl and many more consider 
Tcl their secret competitive edge. 


1.1.1 The Standard Tcl Distribution 


Tcl is usually distributed with two interpreters (tc1sh and wish), documentation and support libraries. 
Tclsh (pronounced as ticklish) is a text-based interpreter and wish is that basic interpreter with Tk 
graphics commands added. 

You can use the Tcl interpreter (tc1sh) as you would use UNIX shell scripts or MS-DOS batch 
(. bat) scripts to control and link other programs or use wish to create GUI interfaces to these scripts. 
The tclsh interpreter provides a more powerful environment than the standard UNIX shell or . bat 
file interpreters. 

The Tcl documentation facility integrates into the native look and feel of the platform Tcl is 
installed on. 


1.1.2 Documentation 


On a UNIX/Linux platform, the man pages will be installed under installationDirectory/ 
man/mann, and can be accessed using the man command. You may need to add the path to the installed 
manual pages to your MANPATH environment variable. 

On Microsoft Windows platforms, you can access the Tcl help from the Start menu, shown in the 
following illustration. 
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This will open a window for selecting which help you need. The window is shown in the following 
illustration. 
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Selecting Tcl Manual/Tcl Built-In Commands/List Handling from that menu will open a win- 
dow like that shown in the following illustration. You can select from this window the page of help 


you need. 
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A Macintosh running Mac OS X comes with Tcl/Tk installed. You can access the man pages by 
opening a terminal window and typing man CommandName as shown in the following illustration. 


public-68-117:TCL_STUFF clif$ man lset 


Iset(n)} Tel Built-In Commands lset(n) 


| NAME 
lset - Change an element ina list 


"SYNOPSIS 
| lset varName ?index...? newValue 


| DESCRIPTION 
The lset command accepts a parameter, varName, which it interprets as 
the name of a variable containing a Tcl list. It also accepts zero or 
more indices into the list. The indices may be presented either con- 
secutively on the command line, or grouped ina Tel list and presented 
as a single argument. Finally, it accepts a new value for an element 
of varName. 


If no indices are presented, the command takes the form: 
lset varName newValue 
or 


If you install a non-Apple version of the tclsh and wish interpreters (for instance whatever 
the latest ActiveState release is), the new man pages will be installed in a location defined by the 
installation. 

The following image shows a Safari view of the ActiveState html man pages for Tcl 8.6. 


ActiveTcl Documentation 


TABLE OF CONTENTS 


Welcome 

Installation Guide ActiveTci User Guipe 
License 

Release Notes 

Package Documentation 


Copyright © 2001 - 2008 ActiveState TcL TuTORI 


Software Inc.. 
All Rights Reserved. 


1. Introduction 
2. Simple Text Output 


6 CHAPTER 1 Tcl/Tk Features 


1.2 TCL AS A GLUE LANGUAGE 


A command glue language is used to merge several programs into a single application. UNIX pro- 
grammers are familiar with the concept of using the output from one program as the input of another 
via pipes. With a glue language, more complex links between programs become possible. Instead of 
the linear data flow of a set of piped programs, you can have a tree-like data flow in which several sets 
of data flow into one application. For example, several programs that report network behavior can be 
merged with a glue language to create a network activity monitor. 

There are good reasons to use simple glue language scripts in your day-to-day computing work. 


e A script can glue existing programs into a new entity. It is frequently faster to glue together several 
small programs to perform a specific task than it is to write a program from scratch. 

e A script can repeat a set of actions faster and more reliably than you can type. This is not to 
disparage your typing skills, but if you have to process 50 files in some consistent manner it will be 
faster to type a five-line script and have that loop through the file names than to type the same line 
50 times. 

e You can automate actions that would otherwise take several sets of window and mouse opera- 
tions. If you have spent much time with GUI programs using Microsoft Windows, Mac OS, or 
the X Window System, you have probably noticed that there are certain operations you end up 
doing over and over again, without a hot button you can use to invoke a particular set of but- 
ton and mouse events. With a scripting language, you can automate a set of actions you perform 
frequently. 

e The script provides a record of commands and can act as procedure documentation. 


If you have written scripts using the Bourne shell under UNIX, or . bat files under MS-DOS/MS- 
Windows, you know how painful it can be to make several programs work together. The constructs 
that make a good interactive user shell don’t necessarily make a good scripting language. 

Using Tcl, you can invoke other programs, just as you would with shell or . bat scripts, and read 
any output from those programs into the script for further processing. Tcl provides the string processing 
and math functionality of awk, sed, and expr without needing to execute other programs. It is easier 
to write Tcl scripts than Bourne shell scripts with awk and sed, since you have to remember only a 
single language syntax. Tcl scripts also run more efficiently, since the processing is done within a single 
executable instead of constantly executing new copies of awk, sed, and so on. 

Note that you can only use a script to control programs that support a non-GUI interface. Many 
GUI-based programs have a command line interface suitable for scripting. Others may support script 
languages of their own or have a dialog-based mode. Under MS Windows, you can also interact 
applications using Tcl’s DDE and COM extensions. 

You can use a wish script as a wrapper around a set of programs originally designed for a text- 
based user interaction (query/response, or one-at-a-time menu choices) and convert the programs into 
a modern GUI-based package. This is a very nice way of adding a midlife kicker to an older package 
by hiding the old-style interactions from users more accustomed to graphical environments. 

For example, we used a text-based problem-tracking system at one company. The user interface 
was a series of questions, such as “What product is the problem being reported against?” and “What 
revision is this product?” A new wish front end had buttons to select the products, text entry fields 
for the revisions and problem descriptions, and so on. This GUI invoked the old user interface when 
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the Submit button was pressed and relayed the selected values to that program as the prompts were 
received. 

The GUI interface reduced the time and error count associated with filling out a report by reduc- 
ing the amount of typing by providing a set of choices for models and revisions. This technique for 
updating the user interface is faster than rewriting the application and is less prone to introducing new 
errors, since all original (debugged) code is left untouched. 


1.2.1 Tel Scripts Compared with UNIX Shell Scripts 
The following are advantages Tcl provides over UNIX shell scripts. 


e Easier handling of program output. Parsing program output in a shell script is possible but not 
always easy. With Tcl, it is simple. Instead of saving the original command line variables, changing 
the field separator, reading a line of output and using the shell set command to parse the line into 
new command arguments, or invoking sed or awk to process some text, you can read a line from 
a program’s output just as if it had been entered at a keyboard. Then you can use Tcl’s powerful 
string and list operators to process the input, assign values to variables, perform calculations, and 
so on. 

e¢ More consistent error handling in Tcl. It can be difficult to distinguish between an error return 
and valid output in shell programming. Tcl provides a mechanism that separates the success/failure 
return of a program from the textual output. 

¢ Consistent language. When you write UNIX shell scripts, you end up using copies of awk and 
sed to perform processing the shell cannot do. You spend part of your time remembering the 
arcane awk and sed command syntax, as well as the shell syntax. Using Tcl, you can use a single 
language to perform all of the tasks, such as program invocation, string manipulation, and com- 
putations. You can expend your effort solving the original problem instead of solving language 
issues. 

e Speed. A single self-contained script running within the Tcl interpreter is faster and uses fewer 

machine resources than a UNIX shell script that frequently needs to spawn other programs. 
This is not to say that a program written in Tcl is faster than one written in the C language. A 
string-searching program written in Tcl is probably slower than a string-searching program written 
in C. But a script that needs to find strings may run faster with a string-searching subroutine in Tcl 
than one written for the UNIX shell that constantly forks copies of another executable. When it is 
appropriate to invoke a special-purpose program, it is easily done with the Tcl exec command. 

e¢ GUI support. You can use Tk to add a graphical interface to your scripts. Under UNIX, wish 
supports the Motif look and feel. Under Windows and Mac, Tk supports the native Windows or 
Macintosh look and feel. 


According to reports in comp.lang.tcl, a GUI written with wish sometimes runs faster than the same 
GUI written in C with the Motif library. For lightweight GUIs, a Tk GUI is frequently faster than a 
Java GUI. 


1.2.2 Tel Scripts Compared with MS-DOS . bat Files 


Tcl has so much more power than . bat files that there is actually very little comparison. The power 
of Tcl/Tk more closely resembles that of Visual Basic. Tcl/Tk is compared to Visual Basic in the next 
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section, in the context of comparison of general-purpose interpreters. The following are advantages a 
Tcl script provides over an MS-DOS .bat file. 


1.3 


Access to the output of programs invoked from script. The .bat file interpreter simply allows you 
to run programs, not to access a program’s output. With Tcl you can start a program, read its output 
into your script, process that data, send data back to that task, or invoke another task with the 
modified data. 

Control structures. Tcl has more control structures than .bat files, including while loops, for 
loops, if /else, and switch. 

String manipulation. The .bat files do not support any string manipulation commands. Tcl 
provides a very rich set of string searching and manipulation commands. 

Math operations. Tcl provides a full set of arithmetic functions, including arithmetic, trig, and 
exponential functions and multiple levels of parentheses. 

Program control. An MS-DOS .bat file has very limited control of other programs invoked by 
the .bat file. Tcl provides a great deal of control. In particular, when a GUI program is invoked 
from a .bat file under Windows 95 or Windows NT, the control may return to the . bat file before 
the program has ended. This is a problem if you were intending to make use of the results of the 
first program you invoked in the next program. Tcl can prevent the second program from starting 
until after the first program has completed its processing, or allow multiple programs to be run 
simultaneously. 

GUI support. You can use Tk to make your scripts into GUIs. Wish supports a look and feel that 
matches the standard MS Windows look and feel, and thus scripts you write with wish will look just 
like programs written in Visual C++, Visual Basic, or other Microsoft development environments. 


TCL AS A GENERAL-PURPOSE INTERPRETER 


The Tcl/Tk interpreter provides the following advantages over other interpreters. 


Multi-platform. The same script can be run under Microsoft Windows 3.1, Microsoft Windows 
95/98, Microsoft Windows NT/2000/XP/Vista/System 7, Apple Mac OS and OS/X, and UNIX or 
Linux. Tcl has also been ported to Digital Equipment’s VMS, PC-DOS, and real-time kernels, such 
as Wind River Systems’ VxWorks, and even to platforms such as Palm OS and Win CE. 
Speed. Since version 8.0 (released in 1998), the Tcl interpreter performs a runtime compilation of 
a script into a byte code. Running the compiled code allows a Tcl script to run faster than Visual 
Basic or Perl. 
EaWer Tcl supports most of the modern programming constructs. 
e Object-oriented programming with classes, supers, and mixins. 
Modularization in the form of subroutines, libraries (including version control), and 
namespaces. 
e Standard program flow constructs: if, while, for, foreach, and switch. 
Rich set of variable types: integers, floating point, strings, lists, dicts and associative arrays. 
e Exception handling. The Tcl catch and error commands provide an easy method of handling 
error conditions. 
e Support for traditional program flow and event-driven programming. 
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¢ Rich I/O implementation. Tcl can perform I/O operations with files, devices, keyboard/screen, other 
programs, or sockets. 

e Powerful string manipulation commands. Tcl includes commands for searching and replacing 
strings or single characters, extracting and replacing portions of strings, and converting strings 
into lists, as well as commands that implement regular expressions for searching and replacing text. 

e Extensibility. Tcl extensions add a few new commands to the Tcl/Tk language to extend the inter- 
preter into a new application domain. This allows you to build on previous development and greatly 
reduces startup time when working on a new problem, in that you only need to learn a couple of 
new commands, instead of an entire new language. 


1.3.1 Tel/Tk Compared to Visual Basic 


Of the currently available languages, Visual Basic is probably the closest in functionality to Tcl/Tk. 
The following are reasons Tcl/Tk is a better choice. 


e Tcl/Tk scripts run on multiple platforms. Although the primary market for software may be the MS 
Windows market, you might also want to have Apple and UNIX markets available to your sales 
staff. 

e Tcl/Tk scripts have support for Internet-style distributed processing, including a secure—safe 
interpreter that allows an application to run untrusted applications securely. 

e Tk provides more and finer control of widgets. Wish allows you to bind actions to graphics objects 
as small as a single character in a text window or as large as an application window. 

e Tcl has better support for library modules and version levels. A Tcl script can check for a particular 
version of its support libraries and not run if they are not available. 


You might prefer Visual Basic over Tcl if you are writing a package that will only need to inter- 
act with the Microsoft applications. Many Microsoft applications use Visual Basic as their scripting 
language and there are off-the-shelf components written in Visual Basic you can merge into these 
applications. Native Tcl supports only the DDE interprocess communication protocol for interacting 
with other MS Windows applications. 

Support for OLE and COM objects can be added to Tcl with the TOCX extension, available at 
www.cs.cornell.edu/Info/Projects/zeno/tocx/. Support for SOAP can be added with the Tcl SOAP 
extension, available at http://tclsoap.sourceforge.net/. The eagle implementation of Tcl , available at 
http://eagle.to, provides complete interaction with the .NET architecture within a CLR virtual machine. 


1.3.2 Tcl/Tk Compared to Perl 


Tcl/Tk often competes with Perl as an application scripting language. The following are advantages 
Tcl/Tk offers over Perl. 


e Simpler syntax. Tcl code can be more easily maintained than Perl code. The rich set of con- 
structs available to Perl programmers allows some very write-only programming styles. A Perl 
programmer can write code that strongly resembles UNIX shell language, C code, or awk scripts. 
Tcl supports fewer syntactic methods of accomplishing the same action, making Tcl code more 
readable. 
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e Speed. The Tcl 8.0 interpreter’s byte-compiled code ran as fast or faster than Perl 5 interpreter code. 
The byte-code engine has continued to be enhanced with a major rework appearing in 8.6. 

e Better GUI support. Native Perl has no GUI support. A couple of Tk-Perl mergers are available, 
but Tk is better integrated with Tcl. 

e Internationalization. Tcl has had fully integrated Unicode support since the 8.1 release (in 1999). 
Tcl 8.6 includes a new time and date package that understands all time zones. 

e Thread safety. While Tcl does not support multiple threads, the Tcl interpreter is thread safe, and 
can be used with multi-threaded applications. Multiple threads can be written in pure Tcl with the 
threads package described in Chapter 16. 


1.3.3 Tcl/Tk Compared to Python 


The base Python interpreter is probably the closest to Tcl in functionality and use. Both are inter- 
preted scripting languages designed to either glue other applications into a new super-application or to 
construct new applications from scratch, and both support easy extension with new C library packages. 

The Python and Tcl developers actively adopt each other’s ideas, leading to a condition in which 
the best features of each language are in both languages (and if that is not true at this moment, it will 
be true again soon). Many programmers know both languages, and the use of one over the other is as 
much personal preference as anything. 

The following are the advantages of Tcl. 


e Simpler syntax. The Tcl language is a bit simpler and easier to learn than Python. 

e Integrated with Tk. Both Python and Perl have adopted the Tk graphics library as their graphics 
package. The integration of Tk with Tcl is cleaner than the integration with either Perl or Python. 
(After all, Tk was designed to work with Tcl.) 

¢ Choice for object-oriented. The Tcl interpreter supports dynamic object-oriented programming with 
the Tc100 commands, or C++/Java style of object-oriented programming with the [incr Tcl] 
extension, but does not require that you use either. 


Python is built around a concept of objects that does not quite match the C++/Java class model, 
and there is no Python extension to get a complete object-oriented behavior with public, protected, and 
private data. The [incr Tcl] extension supports the full C++/Java model of object oriented coding. 
TclOO supports many models including inheritance, delegation, and mixins, giving a developer the 
freedom to choose the architecture that best models the problem being solved. 


1.3.4 Tcl/Tk Compared to Java 


The primary language for multi-platform applications today is Java. Tcl and Java have some similarities 
but are really designed to solve two different problem sets. Java is a system programming language, 
similar to C and C++, whereas Tcl is an interpreted scripting language. In fact, you can write Tcl 
extensions in Java, and Tcl can load and execute Java code. The following are advantages Tcl offers 
over Java. 


e Better multi-platform support. Tcl runs on more platforms than Java. Java requires thread support, 
which is unavailable on many older UNIX platforms. Tcl has also been ported to real-time kernels 
such as VxWorks and Q-nix. 
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e Faster for prototyping. The strength of an object-oriented language is that it makes you think about 
the problem up front and to perform a careful design before you code. Unfortunately, for many 
projects, you do not know the requirements up front and cannot design a class structure until you 
understand the solutions better. Tcl/Tk is great for whipping out a quick prototype, seeing what 
truly answers the user’s needs and what was not necessary, and then creating a serious design from 
a solid set of requirements. 

e Better GUI support. The Tk widgets are easier to work with and provide higher-level support than 
the Java graphics library. 

¢ Configurable security levels. Tcl supports a different security model than the Java Applet model, 
making Tcl an ideal language for Internet program development. With Tcl, objects with various 
origins can be given varying levels of access to your system. By default, the Tcl browser plug-in 
module comes with three security levels: untrusted (no access to file system or sockets), slightly 
trusted (can read files, or sockets, but not both), and fully trusted (can access all I/O types.) With 
Tcl, you can configure your own security model, allowing access to a subset of the file system or 
specific devices, for instance. 

e Smaller downloadable objects. Because the Tcl libraries live on the machine where an application 
runs, there is less to download with a Tcl/Tk application than a similar set of functionality written 
in Java. 


1.4 TCL AS AN EXTENSIBLE INTERPRETER 


Many programming groups these days have a set of legacy code, a set of missions, and a need to 
perform some sort of rapid development. Tcl can be used to glue these code pieces into new applica- 
tions. Using Tcl, you can take the existing project libraries and turn them into commands within a Tcl 
interpreter. Once this is done, you have a language you can use to develop rapid prototypes or even 
shippable programs. 

Merging the existing libraries into the interpreter gives you a chance to hide sets of calling con- 
ventions that may have grown over several years (and projects) and thus expose the application 
programmer to a consistent application programmer interface (API). This technique gives you a chance 
to graft a graphics interface over older, non GUI-based sets of code. 


1.5 TCL AS AN EMBEDDABLE INTERPRETER 


Programs frequently start as a simple proof of concept with hard-coded values. These values quickly 
evolve into variables that can be set with command line arguments. Shortly after that, the command 
lines get unwieldy, and someone adds a configuration file and a small interpreter to parse the configu- 
ration. The macro language then grows to control program flow as well as variables. Then it starts to 
get messy. 

At the point where you need a configuration file, you can merge in a Tcl interpreter instead of 
writing new code to parse the configuration file. You can use Tcl calls to interpret the configuration 
file, and as the requirements expand you will already have a complete interpreter available, instead of 
hacking in features as people request them. 
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Embedding a Tcl interpreter is also a way to add functionality that isn’t easily available in the 
original program. A C, Java or FORTRAN backbone can invoke Tcl scripts to create a GUI, add 
network support or user-level scripting. 


1.6 TCL AS A RAPID DEVELOPMENT TOOL 


Tcl has a simple and consistent syntax at its core, which makes it an easy language to learn. At the 
edges, Tcl has many powerful extensions that provide less commonly needed functionality. These 
extensions include the following: 


e General-purpose programming extensions such as Tcl X (new commands to make Tcl more useful 
for sys-admins) and [incr Tc1] (a full-featured object-oriented extension). 

e Application-specific extensions such as OraTcl and SybTcl (for controlling Oracle or Sybase 
database engines). Tcl 8.6 introduces the tdbc package with database-neutral support for many 
databases including MySQL and SQLite. 

e Special-purpose hardware extensions such as the extensions for controlling Smartbits and Ixia 
broadband test equipment. 

e Special-purpose software libraries such as the TSIPP extension, which lets you generate 3D images 
from a Tcl script using the SIPP library. 


You can think of Tcl as a simple language with a rich set of libraries. You can learn enough of the 
core Tcl commands to start writing programs in under an hour, and then extend your knowledge as 
the need arises. When a task requires some new tools (SQL database interface, for instance), you have 
to learn only those new commands, not an entire new language. This common core with extensions 
makes your life as a programmer easier. You can take all the knowledge you gained doing one project 
and apply most of it to your next project. 

This simplicity at the core with complexity in the extensions makes Tcl/Tk very suitable for rapid 
prototype development projects. During the 1995 Tcl/Tk Workshop, Brion Sarachan described the 
product that General Electric developed for NBC to control television network distribution (the paper 
describing this work is printed in the Conference Proceedings of the Tcl/Tk Workshop, July 1995). 

The first meeting was held before the contract was awarded and included the engineers, man- 
agement, and sales staff. After discussing the basic requirements, the sales and management groups 
continued to discuss schedules, pricing, and such, while the engineers went into another room and put 
together a prototype for what the system might look like. By the time the sales and management staff 
were done, the engineers had a prototype to show. This turnaround speed had a lot to do with GE being 
awarded that contract. 

The GE group expanded their prototype systems with various levels of functionality for the people 
at NBC to evaluate. As the project matured, the specifications were changed on the basis of the expe- 
rience with prototypes. The ease with which Tcl/Tk code can be extended and modified makes it an 
ideal platform for this type of a project. 

The ability to extend the interpreter is a feature that separates Tcl from the other multi-platform 
and rapid development languages. Tcl interpreters can be extended in several ways, ranging from 
adding more Tcl subroutines (called procs in Tcl) to merging C, Java, or even assembly code into 
the interpreter. 
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Studies have found that 80% of a program’s runtime is spent in 20% of the code. The extensible 
nature of Tcl allows you to win at that game by rewriting the compute-intensive portion in a faster 
language while leaving the bulk of the code in the more easily maintained and modified script language. 

This form of extensibility makes Tcl/Tk useful as the basis for a suite of programs. In a rapid 
prototype phase, a Tcl/Tk project can evolve from a simple set of back-of-the-envelope designs to a 
quick prototype done entirely in Tcl. As the project matures, the various subroutines can be modified 
quickly and easily, as they are all written in Tcl. Once the design and the main program flow have 
stabilized, various Tcl/Tk subroutines can be rewritten in C or Java to obtain the required performance. 

Once one project has evolved to this state, you have an interpreter with a set of specialized com- 
mands that can be used to develop other projects in this problem domain. This gives you a platform for 
better rapid prototyping and for code reuse. 


1.7 GUI-BASED PROGRAMMING 


The Tcl distribution includes the Tk graphics extensions of Tcl. The Tk extension package provides 
an extremely rich set of GUI tools, ranging from primitive widgets (such as buttons, menus, drawing 
surfaces, text windows, and scrollbars) to complex compound widgets such as file selectors. 

Any visual object can have a script bound to it so that when a given event happens a particular set 
of commands is executed. For example, you can instruct a graphics object to change color when the 
cursor passes over it. You can bind actions to objects as trivial as a single punctuation mark in a text 
document or as large as an entire display. 

Chapters 11 through 14 describe using Tk to build simple GUIs, active documents (such as maps 
and blueprints) that will respond to user actions, and complex, custom graphics objects. 


1.8 SHIPPING PRODUCTS 


When it comes time to ship a product, you can either ship the Tcl scripts and Tcl interpreter or merge 
your Tcl script into an interpreter to create a Tcl-based executable. The advantage of shipping the Tcl 
scripts is that competent users (or clever programs) can modify and customize the scripts easily. The 
disadvantages include the need for the user to have the proper revision level of Tcl available for the 
script to run and the possibility that someone will reverse engineer your program. 

A Tcl script can be wrapped into a copy of the interpreter, to create a binary executable that will 
run only this script. (See the discussions of starkit, ActiveState’s tclapp, and Dennis Labelle’s 
Freewrap in Chapter 18.) With these techniques, you can develop your program in a rapid develop- 
ment environment and ship a single program that does not require installation of the Tcl interpreter and 
has no human-readable code. 


1.9 BOTTOM LINE 
Tel/Tk is 


e A shell scripting language 
e A multi-platform language 


SSS 
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CHAPTER 1 Tcl/Tk Features 


An extensible interpreter 
An embeddable interpreter 
A graphics programming language 


Tcl/Tk is useful for 


Rapid prototyping 

Shippable product 

Use-once-and-dispose scripts 

Mission-critical, 24/7 applications 

GUI-based projects 

Multi-platform products 

Adding GUIs to existing text-oriented programs 
Adding new functionality to old code libraries 
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.10 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range ___ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 


200-299 These quick exercises require some thought or information beyond that covered in the 


800-399 Long exercises may require reading other material or writing a few hundred lines of 


answered in a few words or a 1-5 line script. These problems should each take under a 
minute to answer. 


chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 


code. These exercises may take several hours to complete. 


100 Can a Tcl script invoke other programs? 

101 Can Tcl scripts perform math operations? 

102 Is Tcl useful for rapid development? 

103 Who developed the Tcl language? Where? Why? 


104 Which of these statements is correct? Tcl is 
e A single language 

e A language core with many extensions 

e A graphics language 


105 How would you deploy a Tcl/Tk program if you could not be certain the client will have the 
right Tcl/Tk version installed on their system? 


1.10 Problems 15 


106 Can a Tcl interpreter be extended with another library? 

107 Can the Tcl interpreter be embedded into another application? 

200 Why would you use Tcl instead of C? 

201 Why would you use C or C++ instead of Tcl? 

202 Why would you use Tcl instead of a .bat file? 

203 What type of requirement would preclude Tcl as the sole development language? 


300 Some computer languages were developed to solve problems in a particular domain (SQL for 
database manipulation, COBOL for business applications, FORTRAN for calculations). Others 
were developed to support particular programming styles (functional languages such as Scheme 
and Lisp, object-oriented languages such as C++ and Java). Other groups of languages were 
created by developers who wanted a new, better tool (C for system development, Perl for systems 
scripts). Describe the strengths and weaknesses of each of these design philosophies. 


30] Tcl can be used to glue small applications into a single larger application, to merge the 
functionality of multiple libraries into a single application, or to write completely self-contained 
applications. Why would you use one technique over another? 


CHAPTER 


The Mechanics of Using the 
Tcl and Tk Interpreters 


The first step in learning a new computer language is learning to run the interpreter/compiler and 
creating simple executable programs. This chapter explores the following. 


e The mechanics of starting the interpreters 

e Starting tclsh and wish scripts in interactive mode 
e Exiting the interpreter 

e Running tclsh and wish scripts from files 


2.1 THE tclsh AND wish INTERPRETERS 


The standard Tcl/Tk binary distribution includes the following two interpreters. 


e tclsh A text-oriented interpreter that includes the core commands, looping constructs, data types, 
I/O, procedures, and so on. Tc1sh is useful for applications that do not require a GUI. 

e wish A GUlI-oriented extension to the tclsh interpreter. The wish interpreter includes the core 
Tcl interpreter, with all commands tclsh supports plus the Tk graphics extensions. 


The simplest way to get started playing with Tcl and Tk is to type your commands directly into the 
interpreter. If you do not already have Tcl installed on your system, see the instructions for installing 
Tcl/Tk on the companion website. 


2.1.1 Starting the tclsh and wish Interpreters 


You can invoke the tclsh and wish interpreters from a menu (in a GUI environment) or from a com- 
mand line (with or without additional arguments). Invoking the interpreters from a menu or a command 
line without arguments starts the interpreter in interactive mode: the interpreter evaluates the com- 
mands as you type them. Invoking the interpreter from a command line with a file name argument (or 
by dragging a file with a Tcl script to the interpreter icon) will cause the interpreter to evaluate the 
script in that file. 

The command line to invoke the tcl sh or wish interpreter from a shell prompt under UNIX, Linux 
or Mac OS/X resembles the following. The question marks (?) indicate optional arguments. 


/usr/local/bin/tclsh ?scriptName? ?options? 


If you invoke tclsh from a .bat file, MS-DOS command window, or Run menu under Microsoft 
Windows, the command would resemble the following. 


C:\tcl\bin\wish.exe ?scriptName? ?options? 


Tel/Tk: A Developer’s Guide. DOI: 10.1016/B978-0-12-384717-1.00002-6 1 7 
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The exact path may vary from installation to installation, and the name of the tc1 sh or wi sh interpreter 
may vary slightly depending on how Tcl was installed. The default installation name for the interpreters 
includes the revision level (e.g., wish8.6), but many sites link the name wi sh to the latest version of 
the wish interpreter. The example paths and interpreter names used throughout this book will reflect 
some of the variants you can expect. 

The command line options can tune the appearance of the wish graphics window. You can define 
the color map, the name of the window, the size of the initial window, and other parameters on the 
command line. Some of these options are system dependent, so you should check your on-line docu- 
mentation for the options available on your system. See Section 1.1.2 for a discussion on how to access 
the on-line help on UNIX, Macintosh, and Windows platforms. 

If there are flags the Tcl interpreter does not parse, those arguments will be ignored by the tclsh 
or wi Sh interpreter and passed directly to the script for evaluation. 

A command line such as the following would invoke the wish interpreter and cause it to evaluate 
the code in the file myapp.tcl. 


wish myapp.tcl -name "My application" -config myconfig.cnf 


The wish interpreter recognizes the - name flag, and thus the arguments -name "My application" 
would cause the window to be opened with the string My application in the window decoration. 
The interpreter does not support a - config flag, and thus the arguments -config myconfig.cnf 
would be passed to the script to evaluate. 


2.1.2 Starting tclsh or wish under UNIX 

Under UNIX, you start tclsh or wish as you would start any other program: type tc1sh (or wish) 
at a shell prompt. If the directory containing the interpreter you want to invoke is in your $PATH, you 
can invoke the interpreter by name, as follows. 


wish ?scriptName? ?wish options? ?script Arguments? 


If your $PATH does not include the directory that contains the tcl sh executable, you would need to 
use the full path, as follows: 


/usr/local/bin/tclsh ?scriptName? ?scriptArguments? 


When tclsh is run with no command line, it will display a % prompt to let you know the interpreter 
is ready to accept commands. When wish starts up, it will open a new window for graphics and will 
prompt the user with a % prompt in the window where you invoked wish. Starting wish and typing a 
short script at the prompt would resemble the following. 


"Hello. World" 


= po J | 


[Heto, wort | 
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Errors Caused by Improper Installation 

When the tcl sh or wish interpreter starts, it loads several Tcl script files to define certain commands. 
The location for these files is set when the interpreter is installed. If an interpreter is moved without 
being reinstalled, or the support file directories become unreadable, you may get an error message 
resembling the following when you try to run tcl sh. 


application-specific initialization failed: 
Can’t find a usable init.tcl in the following directories: 
/usr/local/lib/tcl8.6 /usr/local/lib/tcl8.6 /usr/lib/tcl8.6 
/usr/local/library /usr/library /usr/tcl8.6a4/library 
/tcl8.6a4/library /usr/local/lib/tcl8.6 


This probably means that Tcl wasn’t installed properly. 


You might obtain the following when you try to run wish. 


Application initialization failed: 
Can’t find a usable tk.tcl in the following directories: 
/usr/local/lib/tk8.6 /usr/local/lib/tk8.6 /usr/lib/tk8.6 
/usr/local/library /usr/library /usr/tk8.6a4/library 
/tk8.6a4/library 


This probably means that tk wasn’t installed properly. 


The tclsh and wish interpreters try several algorithms to find their configuration files. Sometimes 
this will result in the same directory being checked several times. This is normal, and does not indicate 
any problem. 

If you receive an error message like these, you should reinstall Tcl/Tk, or restore the init.tcl, 
tk.tcl, and other files to one of the directories listed in the default search paths. Alternatively, you 
can find the directory that includes the appropriate init.tcl and tk.tcl and redefine where the 
interpreters will look for their configuration files by setting the environment variables TCL_LIBRARY 


and TK_LIBRARY to the new directories. 

You can set the environment variable at your command line or in your .profile, .dtprofile, 
.login, .cshrc, or .bashrc configuration file. Using Bourne shell, Korn shell, or bash, this 
command would resemble: 


TCL_LIBRARY=/usr/local/lib/tcl8.6 ; export TCL_LIBRARY 
Using csh, tcsh, or zsh, the command would resemble: 


setenv TCL_LIBRARY /usr/local/lib/tcl8.6 


2.1.3 Starting tclsh or wish under Microsoft Windows 

When you install Tcl under Microsoft Windows, it will create a Tcl menu entry under the Programs 
menu, and within that menu entries for tc1sh and wish. When you select the tcl sh menu item, Tcl 
will create a window for you with the tclsh prompt (%). If you select the wish menu item, wish will 
open two windows: one for commands and one to display graphics. 
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You can also invoke tclsh from an MS-DOS prompt by typing the complete path and command 
name. Note that you may need to use the 8.3 version of a directory name. Windows NT/2000/XP/Vista 
examples resemble this: 


C:> \Program Files\tcl\bin\tclsh86.exe 
C:> \Program Files\tcl\bin\wish86.exe 


Windows 95/98/ME examples resemble this: 


C:> \Progra~1\tcl\bin\tclsh.exe 
C:> \Progra~1\tcl\bin\wish.exe 


The following illustration shows wish being invoked by clicking an icon in the Windows File Explorer. 
Once you see the window with the % prompt (as shown in the following illustration), you can type 
commands directly to the wish shell. The commands you enter will be interpreted immediately. If you 
type a command which command creates a graphic widget, it will be displayed in the graphics window. 


Aw... (- (B)K) 
‘ch [j= Folders (a) ele’ = al 


KT activ 


wish8S 
bs os Wish Application (bin) 1 % button .b -text Quit -command exit 
ActiveState Corporation .b 


(bin) 2 * grid .b 


2.1.4 Starting tclsh or wish on the Mac 


Mac OS X includes tc1sh and wish interpreters. You can start the interpreter from a terminal session, 
just as you can with Linux/Unix. 


Terminal — Wish — 


Last login: Mon Mar 22 16:26:16 on console 
clifs-MacBook:~ clif$ wish8.6 
% label .l -text "Hello, World" 

l 


ae wl a A A Wish 
Hello, World 


Making a Desktop Icon 


If you want to have wish available on your desktop, rather than starting it from a terminal: 


1. 
2. 


3. 


Open a new finder window. 


———————— 
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Select the Library, Frameworks, Tk. framework and Versions elements as shown in the 


following image. 
Drag the Wish icon to your desktop. 


Name 
(J Dictionaries 
() Documentation 
(J Extensions 
(J Filesystems 
( Fonts 
() Frameworks 
fo) Frameworks 
(3 NyxAudioAnalysis.framework 
{J PluginManager.framework 
(j R.framework 
{j Tcl.framework 
(9) Tk.framework 
ful Headers 
2. libtkstub8.6.a 
ful PrivateHeaders 


ful Resources 


a ee 
»_ tkConfig.sh 
Y @ Versions 

Y @ 8.6 

>» (J Headers 
_ libtkstub8.6.a 

> (Dj pkgconfig 
> ( PrivateHeaders 
v © Resources 


Date Modified 


Jan 5, 2011 3:19 PM 


Mar 16, 2011 10:37 AM 
Feb 10, 2010 11:43 PM 
Feb 10, 2010 11:43 PM 


Mar 23, 2011 1:11 PM 


Today, 1:30 PM 


Mar 16, 2011 12:47 PM 
Mar 16, 2011 10:35 AM 
Mar 16, 2011 12:49 PM 


Jan 24, 2011 2:55 PM 


Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 


Feb 4, 2011 3:05 PM 


Today, 1:06 PM 
Today, 1:06 PM 
Today, 1:06 PM 


Info.plist 
_) license.terms 


> (0 Scripts 


” Tk.icns 
2 Tk.tiff 


@ wish 


Feb 4, 2011 3:05 PM 
Feb 4, 2011 3:05 PM 
Today, 1:06 PM 
Feb 4, 2011 3:05 PM 
Feb 4, 2011 3:05 PM 
Today, 1:06 PM 


ee ey 


22 CHAPTER 2 The Mechanics of Using the Tcl and Tk Interpreters 


2.1.5 Exiting tclsh or wish 


You can exit a tclsh or wish interactive interpreter session by typing the command exit at the % 
prompt. Under UNIX, you can also exit a wish program by selecting a Destroy icon from the window 
manager or selecting Close or Destroy from a pull-down menu button. 

On Microsoft Windows, you can exit a wish task by clicking on the X at the top right-hand corner 
of the graphics window. To exit tc1sh, use the exit command. 

On a Macintosh, you can exit a wish task by clicking on the red jellybutton on the top left-hand 
corner of the graphics window. To exit tclsh, use the exit command. 


2.2 USING tclsh/wish INTERACTIVELY 


The default tc1sh prompt is a percent sign (%). When you see this prompt either in the window where 
you started tclsh or in a Tcl command window, you can type commands directly into the interpreter. 
Invoking tc1sh in this mode is one way to experiment with commands and become familiar with their 
behavior. 


4 


2.1 Telsh as a Command Shell 


ro 
2.2. 


If you type a command like 1s or dir that is not part of the Tcl language, the interpreter attempts to 
invoke that program as a subprocess and will display the child’s output on your screen. This feature 
only exists when your session is in an interactive mode. This behavior allows you to use the Tcl 
interpreter as a command shell, as well as an interpreter. 

Under UNIX and Mac OS/X, the command interpreters also evaluate shell programs. This is the 
equivalent of having the MS-DOS . bat file interpreter and command. com functionality available at 
the command line. Experienced users use this feature to write small programs from the command line 
to accomplish simple tasks. 

For instance, suppose you give a friend a set of source code, and a few weeks later he returns it 
with a bunch of tweaks and fixes. You may want to go through all the source code to see what has been 
changed in each file before you commit the changes to your revision control system. Using a UNIX- 
style shell, you can compare all files in one directory to files with the same name in another directory 
and place the results in a file with a DIF suffix. The commands at the Bourne, Korn, or Bash shell 
prompt are as follows. 


$ for i in *.c 
do 
diff $i ../otherDir/$i >$i.DIF 
done 


You can use tcl sh to gain this power in the Windows and Macintosh worlds. The code to accomplish 
the same task under Windows using a tc1 sh shell is: 


% foreach i [glob *.c] { 
exec fc $i ../otherDir/$i >$1.DIF 
} 
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If you install the GNU UNIX tools distribution on your platform, you could use the diff program 
instead of fc, and have a “compare all files” script that runs on all platforms. 


2.2.2 Tk Console (tkcon)—An Alternative Interactive tclsh/wish Shell 


Jeffrey Hobbs wrote a useful console program, tkcon, which provides a nicer interface than the simple 
% prompt. A lightweight version program is the default console when you start tc1sh or wish under 
MS Windows. 

You can run tkcon on Mac OS/X and Linux/Unix systems as you would any other Tcl/Tk script. 
This program is included on the companion website. 

The tkcon application provides the following features: 


e A menu-driven history mechanism, to make it easy to find and repeat previous commands. 

e An Emacs-like editor interface to the command line, to make it easy to fix typos or modify previous 
commands slightly. 

e Brace and parenthesis matching, to help you keep your code ordered. 

e Color-coded text, to differentiate commands, data, comments, and so on. 

e The ability to save your commands in a file. This lets you experiment with commands and save 
your work. 

e A menu entry to load and run Tcl command scripts from files. 

e Support for opening several new tkcon displays. 


Note that although tkcon has support for debugging Tcl/Tk scripts, is easier to work with than the 
interactive wish interpreter, can be used to invoke wish scripts, and is more powerful than the Win- 
dows command interpreter, t kcon does not deal well with programs that use stdin to read user input. 
It is designed to help develop Tcl scripts and to execute noninteractive or GUI-oriented executables, 
not as a replacement for the DOS Console or an xterm window. 


2.2.3 Evaluating Scripts Interactively 
The tclsh and wish interpreters can be used interactively as Tcl program interpreters. This section 
will discuss typing a short program at the command prompt. The next section discusses how to run a 


program saved in a file. 
The traditional first program, “Hello, world,” is trivial in Tcl: 


% puts “Hello, world" 
Hello, world 


The puts command sends a string to an I/O channel. The default channel is the standard output 
device. Normally, the standard output is your command window, but the output can be assigned to a 
file, a TCP/IP socket, or a pipe to another program. The Tcl commands that create I/O channels are 
covered in following chapters. 

Printing “Hello, world” is a boring little example, so let’s make it a bit more exciting by using the 
Tk extensions to make it into a graphics program. In this case, you need to invoke the wi sh interpreter 
instead of the tcl sh interpreter. If you are using the Tk Console program to run this example, you will 
need to load the Tk package by selecting the Interp menu, then Packages, and then selecting Load Tk 
from the Packages menu, as shown in the following illustration. 
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File Console Edit Interp Prefs History 


Main console displa SLAVE: slave 
{HTML) 1 % | 


Packages - Load http (1.0 2.3) 
Load Tix (4.1.8.3) 
Load Expect (5.31.7) 


Checkpoint State Load tcltest (1.0) 


Show Last Error 


Revert State Load opt (0.4.1) 


View State Change Load msgcat (1.0) 
Load Tkx (8.2) 
Send TkCon Commands Load Tclx (8.2) 


Load Tk (8.3) 


Typing the following code at the % prompt will display “Hello, world” in a small box in the graphics 
window. 


eee ee ee eee 
Example 1 


Script Code 


label .1 -text "Hello, world" 
grid .] 
| 


The 1 abel command tells the wish interpreter to construct a graphics widget named .1 and place 
the text “Hello, world” within that widget. The grid command causes the label to be displayed. These 
commands are covered in Chapter 11. When you run this script you should see a window resembling 
the following. 


Hello, World 


2.3 EVALUATING TCL SCRIPT FILES 


Typing a short program at the command line is a good start, but it does not create a shippable product. 
The next step is to evaluate a Tcl script stored in a file. 


2.3.1 The Tcl Script File 


A Tel script file is simply an ASCII text file of Tcl commands. The individual commands may be 
terminated with a newline marker (carriage return or line feed) or a semicolon. 

Tcl has no restrictions on line length, but it can be difficult to read (and debug) scripts with com- 
mands that do not fit on a single display line. If a command is too long to fit on a single line, making the 
last character before the newline a backslash will continue the same command line on the next screen 
line. For example, the following is a simple tc] sh script that prints several lines of information. 
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.—_Ha—_A 
Example 2 
Script Code 

puts "This is a simple command" 

puts "this line has two"; puts "commands on it"; 

puts “this line is continued \ 

on the next line, but prints one line" 


Script Output 
This is a simple command 
this line has two 
commands on it 
this line is continued on the next line, but prints one line 


Note that there are two spaces between the words continued and on. When the Tcl interpreter 
evaluates a line with a backslash in it, it replaces the backslash newline combination with a space. 

You can write Tcl/Tk programs with any editor that will let you save a flat ASCII file. 

In the UNIX world, vi, pico and Emacs are common editors. On the MS Windows platforms, 
Notepad, Brief, WordPerfect, and MS Word are suitable editors. The Macintosh editors MacWrite and 
Alpha (and other editors that generate simple ASCII files) are suitable. Note that you must specify an 
ASCII text file for the output and use hard newlines if you use one of the word processor editors. The 
Tcl interpreter does not read most native word processor formats. 

There are several Tcl integrated development environments (IDEs) available, ranging from com- 
mercial packages such as ActiveState’s Komodo and Neatware’s MyrmocoX, to freeware such as 
Eclipse, to tools such as the editor Mike Doyle and Hattie Schroeder developed as an example in 
their book Interactive Web Applications with Tcl/Tk (www.eolas.com/tcl). IDEs are discussed in more 
detail in Chapter 18. 

The free Komodo Edit application from ActiveState runs on Mac OS/X, Windows and several 
flavors of Unix. The Komodo Edit application is midway between a full IDE and a simple editor. It 
provides tips and highlighting for several languages. 

Another free package is the Tcl Plugin for Netbeans, one of the Tcl Community’s Google Summer 
of Code projects. This plugin also provides syntax highlighting. Details about this project are available 
athttp://wiki.tcl.tk/28292. 

You can also use the Tk Console to type in Tcl commands and then save them to a file via the File > 
Save > History menu choice. You will probably need to edit this file after you have saved it, to delete 
extra lines. 


2.3.2 Evaluating Tcl Script Files 
For the time being, let’s assume you have created a file named foo.tcl containing the following text. 


label .1 -text "The arguments to this script are: $argv" 
pack .1 


There are several ways to evaluate this wish script file. The following are two that will work on any 
Mac OSX, Linux, Unix or Microsoft system. Other methods tend to be platform specific, and these are 
covered in the system-specific sections. 
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You can always evaluate a tclsh or wish script by typing the path to the interpreter, followed by 
the script, followed by arguments to the script. This works under Windows (from a Command window, 
or Run menu) or Unix, Linux or Mac OSX and would look as follows. 


C:\tcl8.6\bin\wish86.exe foo.tcl one two three 
or 
/usr/local/bin/wish8.6 foo.tcl one two three 


This will cause a window resembling the following to appear on your display. 


A000 Wish 


The arguments to this script are: one two three 


You can also cause a script to be evaluated by typing source foo.tcl at the % prompt within an 
interactive wish interpreter session. The source command will read and evaluate a script but does not 
support setting command line arguments. Using the source command for the previous examples would 
result in a label that only displayed the text “The arguments to this script are:” with no arguments 
displayed. 


$> wish 
% source foo.tcl 


eCce wish OQ 


The arguments to this script are: 


Evaluating a Tcl Script File under UNIX 
Under UNIX, you can use the technique of placing the name of the interpreter in the first line of the 
script file and using the chmod command to make the script executable. 

chmod +x foo.tcl. 


Unfortunately, the interactive Unix command interpreters (bash, csh, etc.) only search your current 
directory, /bin and /usr/bin for interpreters. If you keep tclsh in another directory (for instance, 
/usr/foo/bin), you will need to start your script files with the complete path, as follows. 


#!/usr/foo/bin/tclsh 


This makes a script less portable, since it will not run on a system that has tcl sh under /usr/bar/bin. 
A clever workaround for this is to start your script file with the following lines. 


dt! /bin/sh 
HA 
exec wish "$0" "$@" 


The trick here is that both Tcl and the shell interpreter use the # to start a comment, but the Bourne 
shell does not treat the \ as a line continuation character the way Tcl does. 
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The first line ( ##! /bin/sh ) invokes the sh shell to execute the script. The shell reads the second 
line (##\), sees a comment, and does not process the \as a continuation character, so it evaluates the 
third line (exec wish "$0" "$@"). At this point, the sh shell searches the directories in your $PATH 
to find a wish interpreter. When it finds one, the sh shell overwrites itself with that wish interpreter 
to execute. Once the wi sh interpreter is running, it evaluates the script again. 

When the wish interpreter reads the script, it interprets the first line as a comment and ignores it, 
and treats the second line (##\) as a comment with a continuation to the next line. This causes the Tcl 
interpreter to ignore exec wish "$0" "$@" as part of the comment started on the previous line, and 
the wish interpreter starts to evaluate the script. 


2.3.4 Evaluating a Tcl Script File under Microsoft Windows 


When Tcl is installed under Windows it establishes an association between the .tc1 suffix and the 
wish interpreter. This allows you to run a .tcl script by typing the script name in the Run menu, or 
via mouse clicks using Windows Explorer, the Find application, and so on. 

If you desire to use other suffixes for your files, you can define tc1sh or wish to process files with 
a given suffix via the Microsoft Windows configuration menus. The following are examples of adding 
a file association between the suffix .tc8 and the tcl sh interpreter. This association will invoke the 
tclsh interpreter to run scripts that are text driven instead of graphics driven. 


Changing File Association on Windows XP and Earlier 
Select My Computer > View > Options, to get the Options display. 
Select the File Types tab from this display and the New Type button from this card. 


Options 
Folder | View File Types | 


Registered file types: 
E] Shortcut into a document 
Shortcut to The Microsoft Network 


=| Text Document 
[>] TrueType Font file 
|x] Type Library 

{3 URL-File Protocol 


=i 
£2) URL:File Transfer Protocol ha 


© AP er 


- File type details 


Extension: Tce 


Content Type (MIME): text/plain 


Opens with: TCLSH80 
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You must provide an open action that points to the interpreter you want to invoke to open files with 
this suffix. The application to perform the action needs a full path to the interpreter. Clicking the New 
button opens this window, where you can enter the open action, and the application to use to open 
the file. 


Add New File Type 


Change Icon... 
Description of type: [Telsh script 


Associated extension: |.tc8 


Content Type (MIME): [text/plain ¥ 


Default Extension for Content Type: | txt v 
Actions: 
open 


Remove 


[~ Enable Quick View IV Confirm open after download 


T~ Always show extension = [~ Growese in same window 


Close | (ance 


Changing File Association on Windows Vista and Windows 7 

The simplest way to add a new file association in Windows Vista and Windows 7 is to create a new file 
with the extension you wish to add, right click the new file and select the Open with and add the new 
application for that extension as shown in the following illustration. 


1. Create a new file: 


View 
Sort by 
Refresh 


Paste 
Paste shortcut 


Undo Delete 


New 
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Ctrl+Z 


Folder 
Shortcut 


Screen resolution 


Gadgets 


Personalize 


Bitmap image 

Contact 

Journal Document 

Rich Text Document 

Text Document 
Compressed (zipped) Folder 


Briefcase 


2. Give it a name with the new extension: 


| New Text Document Properties 


General | Security | Details | Previous Versions 


Type of file: 
Opens with: 


Location: 
Size: 

Size on disk: 
Created: 


Modified: 
Accessed: 


Foo tc8| 


Text Document (bd) 
i Netead 


C:\Users\Carol Flynt\Desktop 
Obytes 
O bytes 


Today, August 16, 2011, 1 minute ago 
Today, August 16, 2011, 1 minute ago 
Today, August 16, 2011, 1 minute ago 


Attributes: 


[] Read-only = [/] Hidden 
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3. Right click the file icon, and select Open with, and select Choose default program... 


Open 


Print 
Edit 
Open with “| Notepad 
[| WordPad 


Share with 


Restore previous versions Choose default program... 
Send to 

Cut 

Copy 


Create shortcut 
Delete 


Rename 


Properties 


4. Click the Browse button at the bottom. 


Open with 
PR Choose the program you want to use to open this file: 
File: Foo. tc8.txt 


Recommended Programs 
~Y) Notepad (RS) wordPad 


Microsoft Corporation (==) Microsoft Corporation 


Other Programs 


[V] Always use the selected program to open this kind of file Browse:ss 


If the program you want is not in the list or on your computer, you can look for the appropriate program on the 


7 _———— 


5. Edit the top line to point to the folder where the Tcl binaries are installed (the common default is 
C:Tcl). Select bin and finally select the application you wish to use to evaluate the .tc8 files. This 
will probably be tclsh or wish. 
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_) Open with... 
Overs « Local Disk(C) » Tel > bin 


Organize v New folder 


: + Name Date modified 
* Favorites 


MD Desktop 2) base-tcl8.6-thread-win32-1x86 2/4/2011 5:55 PM Applicatic 
ik Downloads @ base-tk8.6-thread-win32-ix86 2/4/2011 5:55 PM Applicatic 
S] Recent Places @ tclsh 2/4/2011 4:04 PM Applicatic 
e 2/4/2011 4:04 PM ~—Applicatic 

File description: Tclsh Application my a . a ¥a 
= Company: ActiveState Corporation 2/4/2011 5:55 PM Applicatic 
«| Documents @e File version: 8.6.1.1 4/2011 3:48 PM Applicatic 

: Date created: 8/16/2011 7:25 PM . ‘i 6 

M 2/4/2011 3:48 PM catic 

@) Music |. 4/2011 3:48 PP icatic 


Libraries 


t| Pictures 
# Videos 


1 Computer 
& Local Disk (C:) 
<3 CD Drive (D:) CDI+ <¢ 


File name: Sa | Programs 


Running scripts via the mouse works well for wi sh-based programs that do not require any com- 
mand line arguments. If you need to invoke a script with command line options, you must invoke the 
script from a DOS command window, the Run selection, or via a shortcut. 

You can create a shortcut by right-clicking on an empty space on the Windows screen and select- 
ing the New and Shortcut menu items. In the Shortcut window, enter (or browse to) your Tcl script, 
followed by whatever options you wish, as shown in the following illustration. 


New Action HE 


Action: 


fren — ox | 


ae . Cancel | 
Application used to perform action: 
[C:ATchbin\telsh, exe 


I Use DDE 
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This will create a shortcut on your desktop, and when you click that shortcut Windows will invoke 
the wi sh interpreter to evaluate the script with the command line options you entered. Using a shortcut, 
or the Run menu selection, Microsoft Windows will examine the registry to find out how to evaluate 
your script. If you want to invoke your script from a DOS-style command window, you will need to 
explicitly tell Windows what interpreter to use for the script. A technique that will always work is 
typing the complete path to the interpreter and the name of the script as follows. 


C:\tcl\bin\wish myscript.tcl 


If you do not wish to type ungainly long lines whenever you invoke a script, there are several options. 


e You can add the path to the Tcl interpreter to your DOS path. 
PATH C:\Tcl\bin;C:\Windows ;\C:\Windows\System32 

e You can create a .bat file wrapper to invoke tclsh. This is similar to typing out the entire path 
in some respect, but allows you to put a single small . bat file in C:\WINDOWS, while leaving the 
Tcl interpreter and libraries in separate directories. 
C:\Tcl\bin\tclsh86 %1 %2 %3 %4 %45 %6 %7 %8 %9 

e You can write your Tcl programs as .bat files and evaluate them as filename.bat with the 
following wrapper around the Tcl code. 


::catch {}:4\ 

@echo off 

srcatch {}24\ 
@"C:\Tcl\bin\tclsh.exe" 40 41 %2 
::catch {}34\ 

@goto eof 

dfyour code here 

#\ 

eof 


This is similar to the startup described for UNIX Tcl files. The lines with leading double colons are 
viewed as labels by the . bat file interpreter, whereas the Tcl interpreter evaluates them as commands 
in the global namespace. 

These lines end with a comment followed by a backslash. The backslash is ignored by the . bat file 
interpreter, which then executes the next line. The Tcl interpreter treats the next line as a continuation of 
the previous comment and ignores it. The catch command is discussed in Chapter 5, and namespaces 
are discussed in Chapter 6. 

If you prefer to run your scripts by single word (i.e., fi | ename instead of fi ]lename.bat), youcan 
change the line @"C:\tcl\bin\tclsh.exe" 40 21 %2to@"C:\tcl\bin\tclsh.exe" %0.bat 
%1 %2.The problem with the .bat file techniques is that .bat files support a limited number of 
command line arguments. On the other hand, if you need more than nine command line arguments, 
you might consider using a configuration file. 


2.3.5 Evaluating a Tcl Script on the Mac 


Mac OS X is built over a UNIX kernel, and uses the techniques discussed for UNIX scripts. The 
concept of the executable script file does not really exist on the traditional Mac OS. 
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If you wish to evaluate a previously written script on the Mac, you can select the Source entry from 
the File menu, and then select the file to execute. Alternatively, you can type the command to source 
the script file at the % prompt. In this case, you must use the complete path, as follows. 


source :demos:widget 


2.4 BOTTOM LINE 


e tclshis an interpreter for text-based applications. 

e wish is the tcl sh interpreter with graphics extensions for GUI-based applications. 

e These programs may be used as interactive command shells or as script interpreters. 

e Either interpreter will accept a script to evaluate as a command line argument. A script is an ASCII 
file with commands terminated by newlines or semicolons. In a script, commands may be continued 
across multiple lines by making the final character of a line the backslash character. 

e tclsh scripts may be made executable by wrapping them in . bat files under MS Windows. 

e tclsh scripts may be made executable by setting the execute bit with chmod under UNIX. 

e wish scripts that need no arguments may be executed from a File Explorer or Desktop under MS 
Windows, Mac OSX or Linux/Unix. 

e wish scripts that need arguments may be executed from the command window or the Run menu 
under MS Windows. 

e Arguments after the script file name that are not evaluated by the interpreter will be made available 
to the script being evaluated. 

e The command to exit the tclsh or wish interpreters is exit. 


2.5 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under 
a minute to answer. 


200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 


800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e 100 Can the wish shell be used to execute other programs? 


e 101 Can the text in the window decoration of a wish application be defined from the command 
line? 
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e 102 Cana tclsh or wish script access command line arguments? 


e 103 If you have a private copy of wish in your personal bin account on a UNIX/Linux platform, 
and have that directory in your search path, can you start scripts with #! wish to have them 
evaluated with this copy of wish? Assume the script is located in the bin with the wish 
interpreter, and the current working directory is your $HOME. 


e 104 If you install Tcl on MS Windows under D:\Tc18.6, will scripts with a file name ending in 
. tcl be evaluated by wish when you select them from File Explorer? 


e 105 What is the wish command to create a window with simple text in it? 
e 106 What wish command will cause a window to be displayed? 
e 107 What tclsh command will generate output to a file or device? 


e 200 If you type 1s during an interactive Tcl session, tclsh will attempt to execute the 1s on the 
underlying operating system. Can you include an 1s command in a tcl sh script? Why or why 
not? 


e 201 Write a wish script that has a label with your name in it. 
e 202 Write a tclsh script that prints out several lines on the standard output. 


e¢ 203 What command line would start a wish interpreter with the title “My Wish Application” in 
the window decoration? (UNIX or MS Windows only.) 


e 300 Each window created in wish needs to have a unique name starting with a lowercase letter. 
Write a wish script that creates labels: one label should contain your name, one your favorite 
color, and one a numeric value (which might be the air speed of a swallow). 


e 301 One of the two standard interpreters (wish and tclsh) was ported to MS-DOS 5.0 (not 
Windows). Which was ported, and why not the other? 


CHAPTER 


Introduction to the Icl 
Language 


The next five chapters constitute a Tcl language tutorial. This chapter provides an overview of the 
Tcl syntax, data structures, and enough commands to develop applications. Chapter 4 discusses Tcl 
I/O support for files, pipes, and sockets. Chapters 5—8 introduce more commands and techniques and 
provide examples showing how Tcl data constructs can be used to create complex data constructs such 
as structures and trees. Chapters 9 and 10 introduce the TclOO object-oriented support package and 
explain some tricks in using dynamic and introspective object-oriented programming effectively. 

This introduction to the Tcl language will give you an overview of how to use Tcl, rather than 
be a complete listing of all commands and all options. The on-line reference pages are the complete 
reference for the commands. See Chapter | for a discussion on how to access the on-line help on 
UNIX, Macintosh, and Windows platforms. The companion website contains a Tcl/Tk reference guide 
that contains brief listings of all commands and all options. 

If you prefer a more extensive tutorial, see the tutorials list on the companion website. You will 
find a copy of Tcl Tutor, a computer-assisted instruction program that covers all of the commands in 
Tcl, and most of the command options. 

Chapters 11 through 14 constitute the Tk tutorial. If you are performing graphics programming, 
you may be tempted to skip ahead to those chapters and just read about the GUIs. Don’t do it! Tcl 
is the glue that holds the graphic widgets together. Tk and the other Tcl extensions build on the Tcl 
foundation. If you glance ahead for the Tk tutorial, plan on coming back to fill in the gaps. 

This book will print the command syntax using the font conventions used by the Tcl on-line manual 
and help pages. This convention is as follows. 


commandname The command name appears first in this type font. 

subcommandname If the command supports subcommands, they will also be in this 
type font. 

-option Options appear in italics. The first character is a dash (-). 

argument Arguments to a command appear in italics. 

?-option? Options that are not required are bounded by question marks. 

?argument? Arguments that are not required are bounded by question marks. 


The following is an example. 
Syntax: puts ?-nonewline? ?channel? outputString 


The command name is puts. The puts command will accept the options -nonewl]ine and 
channel as arguments, and must include an outputString argument. 
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3.1 OVERVIEW OF THE BASICS 


The Tcl language has a simple and regular syntax. You can best approach Tcl by learning the overall 
syntax and then learning the individual commands. Because all Tcl extensions use the same base inter- 
preter, they all use the same syntax. This consistency makes it easy to learn new sets of commands 
when the need arises. 


3.1.1 Syntax 


Tcl is a position-based language, not a keyword-based language. Unlike languages such as C, FOR- 
TRAN, and Java, there are no reserved strings. The first word of a Tcl command line must always be 
a Tcl command; either a built-in command, a procedure name, or (when tc1 sh is in interactive mode) 
an external command. 

A complete Tcl command is a list of words. The first word must be a Tcl command name or a 
procedure name. The words that follow may be subcommands, options, or arguments to the command. 
The command is terminated by a newline or a semicolon. 

For example, the word puts at the beginning of a command is a command name, but puts in the 
second position of a command could be a subcommand or a variable name. The Tcl interpreter keeps 
separate hash tables for the command names and the variable names, so you can have both a command 
puts and a variable named puts in the same procedure. The Tcl syntax rules are as follows. 


e The first word of a command line is a command name. 

e Each word in a command line is separated from the other words by one or more spaces. 

e Words can be grouped with double quotes or curly braces. 

e A list can be ungrouped with the three-character {*} operator. 

e¢ Commands are terminated with a newline or semicolon. 

¢ A word starting with a dollar sign ($) must be a variable name. This string will be replaced by the 
value of the variable. 

e A variable name followed by a value within parentheses (no spaces) is an associative array: 
arrayName( index) 

e Words enclosed within square brackets must be a legal Tcl command. This string will be replaced 
by the results of evaluating the command. 


The Tcl interpreter treats a few characters as having special meaning. These characters are as 
follows. 


Substitution Symbols 


$ The word following the dollar sign must be a variable name. Tcl will 
substitute the value assigned to that variable for the $varName string. 
] The words between the square brackets must be a Tcl command string. 


The Tcl interpreter will evaluate the string as acommand. The value 
returned by the command will replace the brackets and string. 
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Grouping Symbols 

a Groups multiple words into a single string. Substitutions will occur within 
this string. 

{} Groups multiple words into a single string. No special character 
interpretation will occur within this string. A newline within curly braces 
does not denote the end of a command, and no variable or command 
substitutions will occur. 

Other 

\ Escapes the single character following the backslash. This character will 
not be treated as a special character. This can be used to escape a dollar 
sign to inhibit substitution, or to escape a newline character to continue a 
command across multiple lines. 

: Marks the end of a command. 

<newline> Marks the end of a command. 

# Marks the rest of the line as a comment. Note that the # must be in a 
position where a Tcl command name could be: either the first character on 
a line or following a semicolon (;). 


oe 
Example 1 
x=4 Not valid: The string x=4 is interpreted as the first word on a line and 
will be evaluated as a procedure or command name. This is not an 
assignment statement. 


Error Message: invalid command name "x=4" 
puts "This command has one argument"; 

Valid: This is a complete command. 
puts one; puts two; 

Valid: This line has two commands. 
puts one puts two 


Not valid: The first puts command is not terminated with a 
semicolon, so Tcl interprets the line as a puts command with three 
arguments. 

Error Message: bad argument "two": should be 
"nonewline" 


3.1.2 Grouping Words 


The spaces between words are important. Since Tcl does not use keywords, it scans commands by 
checking for symbols separated by white space. Tcl uses spaces to determine which words are com- 
mands, subcommands, options, or data. If a data string has multiple words that must be treated as a 
single set of data, the string must be grouped with quotes (“”’) or curly braces ({}). 
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Ee $A AAA 


Example 2 

if { $x > 2} { Valid: If the value of x is greater than 2, the value of greater is set 
set greater true to “true.” 

} 

if{ $x > 2} { Not valid: No space between jf and test left brace. 
set greater true Error Message: invalid command name "if{" 

} 

if {$x > 2}{ Not valid: No space between test and body left brace. 
set greater true Error Message: invalid command name "}" 

} 

set x "a b" Valid: The variable x is assigned the value a b. 

set x {a b} Valid: The variable x is assigned the value a b. 

set x a b Not valid: Too many arguments to set. 


Error Message: wrong # args: should be “set varName 
?newValue?" ma 


The Tcl interpreter treats quotes and braces differently. These differences are discussed later in this 
chapter, and in more detail in Chapter 4. 


3.1.3 Comments 
A comment is denoted by putting a pound sign (#) in the position where a command name could be. 


The Tcl Style Guide recommends that this be the first character on a line, but the pound sign could be 
the first character after a semicolon. 


$$$ ee 


Example 3 
## This is a comment Valid: This is a valid comment. 
puts "test" ; # Comment after a command. 


Valid: But not Recommended style. 


puts "test" # this is a syntax error. 


Not valid: The puts command was not 
terminated. fal 


3.1.4 Data Representation 


Tcl does not require that you declare variables before using them. The first time you assign a value to a 
variable name, the Tcl interpreter allocates space for the data and adds the variable name to the internal 
tables. 

A variable name is an arbitrarily long sequence of letters, numbers, or punctuation characters. 
Although any characters (including spaces) can be used in variable names, the convention is to follow 
naming rules similar to those in C and Pascal; start a variable name with a letter, followed by a sequence 
of alphanumeric characters. 

The usual convention is to start variable names with a lowercase letter. 
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The Tcl Style Guide recommends that you start variable and procedure names that are exported 
from a namespace with a lowercase letter and start variable and procedure names that are only for 
internal use with an uppercase letter. The rationale for this is that items that are intended for internal 
use should require more keystrokes than items intended for external use. This document is available at 
the Tcl/Tk resource (www.tcl.tk/doc/styleGuide.pdf) and on the companion website. 

A variable is referenced by its name. Placing a dollar sign ($) in front of the variable name causes 
the Tcl interpreter to replace the $varName string with the value of that variable. The Tcl interpreter 
always represents the value of a Tcl variable as a printable string within your script. (Internally, it may 
be a floating-point value or an integer. Tcl interpreter internals are described in Chapter 15.) 


$$$ $$ 


Example 4 
set x four Set the value of a variable named x to four. 
set pi 3.14 Set the value of a variable named pi to 3.14. 
puts "pi is $pi" Display the string: pi is 3.14”. 
set pix2 6.28 Set the value of a variable named pi *2 to 6.28. 


set "bad varname" "Don’t Do This" 


Set the value of a variable named bad varnameto Don’t 


Do This. || 


Note that the * symbol in the variable name pi «2 does not mean to multiply. Since the * is embed- 
ded in a word, it is simply another character in a variable name. The last example shows how spaces 
can be embedded in a variable name. This is not recommended style. 


2) 


-5 Command Results 


All Tcl commands return either a data value or an empty string. The data can be assigned to a variable, 
used in a conditional statement such as an i f, or passed to another command. 

The Tcl interpreter will evaluate a command enclosed within square brackets immediately, and 
replace that string with the value returned when the command is evaluated. This is the same as putting 
a command inside backquotes in UNIX shell programming. 

For example, the set command always returns the current value of the variable being assigned 
a value. In the example that follows, when x is assigned the value of "apple", the set command 
returns "apple". When the command set x "pear" is evaluated within the square brackets, it 
returns "pear", which is then assigned to the variable y. 


aa 
Example 5 

i## The set x command returns the contents of the variable. 

% set x “apple” 

apple 

% set y [set x "pear"] 

pear 

% puts $y 

pear 

% puts $x 

pear 
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In the previous example, the quotes around the words app!/e and pear are not required by the Tcl 
interpreter. However, it is good practice to place strings within quotes. 


.6 Errors 


Like other modern languages, Tcl has separate mechanisms for the status and data returns from com- 
mands and functions. If a Tcl command fails to execute for a syntactic reason (incorrect arguments, 
and so on), the interpreter will generate an error and invoke an error handler. The default error handler 
will display a message about the cause of the error and stop evaluating the current Tcl script. 

A script can disable the default error handling by catching the error with the catch command, and 
can generate an error with the error command. 

The catch command is used to catch an error condition without causing a script to abort 
processing. 


Syntax: catch script ?varName? 
script A script to evaluate 
?varName? An optional variable name to receive the results of evaluating the script. 


If the script generates an error, the catch command will return a true (1). If the script runs without 
error, the catch command will return a false (0). If an optional variable name is provided, the return 
value from running the command (either an error message or a return value) is set as that variable’s 
value. 


COMMAND EVALUATION AND SUBSTITUTIONS 


Much of the power of the Tcl language is in the mechanism used to evaluate commands. The evaluation 
process is straightforward and elegant but, like a game of Go, it can catch you by surprise if you do not 
understand how it works. 

Tcl processes commands in two steps. First, it performs command and variable substitutions, and 
then it evaluates the resulting string. Note that everything goes through this evaluation procedure. Both 
internal commands (such as set) and subroutines you write are processed by the same evaluation code. 
A while command, for example, is treated just like any other command. It takes two arguments: a test 
and a body of code to execute if the test is true. 


3.2.1 Substitution 
The first phase in Tcl command processing is substitution. The Tcl interpreter scans commands from 


left to right. During this scan, it replaces phrases that should be substituted with the appropriate values. 
Tcl performs two types of substitutions: 


e A Tcl command within square brackets ([ . . . ]) is replaced by the results of that command. This is 
referred to as command substitution. 

e A variable preceded by a dollar sign is replaced by the value of that variable. This is referred to as 
variable substitution. 


After these substitutions are done, the resulting command string is evaluated. 
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3.2.2 Controlling Substitutions with Quotes, Curly Braces, and the Backslash 


Most Tcl commands expect a defined number of arguments and will generate an error if the wrong 
number of arguments is presented to them. When you need to pass an argument that consists of multiple 
words, you must group the words into a single argument with curly braces or with quotes. 

The difference between grouping with quotes and grouping with braces is that substitutions will be 
performed on strings grouped with quotes but not on strings grouped with braces. Examples 6 and 7 
show the difference between using quotes and curly braces. 

The backslash may be used to disable the special meaning of the character that follows the back- 
slash. You can escape characters such as the dollar sign, quote, or brace to disable their special meaning 
for Tcl. Examples 8 and 9 show the effects of escaping characters. A Tcl script can generate an error 
message with embedded quotes with code, as in the following. 


puts "ERROR: Did not get expected \"+0K\" prompt" 


The following examples show how quotes, braces, and backslashes affect the substitutions. The 
first example places the argument to puts within curly braces. No substitutions will occur. 


OOOO —-:”——n—n— —  ay»E-~>~ 
Example 6 


Script Example 
set x 2 
set y 3 
puts {The sum of $x and $y is returned by [expr $x+$y]} 


Script Output 


The sum of $x and $y is returned by [expr $x+$y] 


In Example 7, puts has its argument enclosed in quotes, so everything is substituted. 


eee 
Example 7 


Script Example 
set x 2 
set y 3 
puts "The sum of $x and $y is [expr $x+$y]" 


Script Output 
The sum of 2 and 3 is 5 


In Example 8, the argument is enclosed in quotes, so substitution occurs, but the square brackets 
are escaped with backslashes to prevent Tcl from performing a command substitution. 
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a 
Example 8 
Script Example 

set x 2 

set y 3 

puts "The sum of $x and $y is returned by \Lexpr $x+$y\]" 


Script Output 


The sum of 2 and 3 is returned by [expr 2+3] 


Example 9 escapes the dollar sign on the variables to prevent them from being substituted and also 
escapes a set of quotes around the expr string. If not for the backslashes before the quotes, the quoted 
string would end with the second quote symbol, which would be a syntax error. Sets of square brackets 
and curly braces nest, but quotes do not. 


$$ 
Example 9 
Script Example 

set x 2 

set y 3 

puts "The sum of \$x + \$y is returned by \"\Lexpr \$xt\$y\J]\"" 


Script Output 


The sum of $x + $y is returned by "[expr $x+$y]" 
| 
Splitting Lists 


The {*} operator will convert a list to its component parts before evaluating a command. This is com- 
monly used when one procedure returns a set of values that need to be passed to another procedure as 
separate values, instead of as a single list. 

The set command requires two arguments to assign a value to a variable - the name of the variable 
and the value. You cannot assign the variable name and value to a string and then pass that string to 
the set command. 


if This is an error 
set nameANDvalue "a 2" 
set $nameANDvalue 


The {*} operator can split the string "a 2" into two components: the letter a and the number 2. 


ee 
Example 10 
Script Example 


if This works 
set nameANDvalue "a 2" 
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set {*«}$nameANDvalue 
puts $a 


Script Output 
2 


3.2.3. Steps in Command Evaluation 
When a Tcl interpreter evaluates a command, it makes only one pass over that command to perform 
substitutions. It does not loop until a variable is fully resolved. However, if a command includes another 
Tcl command within brackets, the command processor will be called recursively until there are no fur- 
ther bracketed commands. When there are no more phrases to be substituted, the command is evaluated, 
and the result is passed to the previous level of recursion to substitute for the bracketed string. 

The next example shows how the interpreter evaluates a command. The indentation depth 
represents the recursion level. Let’s examine the following command. 


set x [expr [set a 3] + 4 + $a] 


The expr command performs a math operation on the supplied arguments and returns the results. 
For example, expr 2+2 would return the value 4. 

The interpreter scans the command from left to right, looking for a phrase to evaluate and substitute. 
The scanner encounters the left square bracket, and the command evaluator is reentered with that subset 
of the command. 


expr [set a 3] + 4 + $a 


The interpreter scans the new command, and again there is a bracket, so the command evaluator is 
called again with the following subset. 


set a 3 


There are no more levels of brackets and no substitutions to perform, so this command is evaluated, 
the variable a is set to the value 3, and 3 is returned. The recursive call returned 3, so the value 3 
replaces the bracketed command, and the command now resembles the following. 


expr 3 + 4 + $a 


The variables are now substituted, and $a is replaced by 3, making the following new command. 


expr 3 + 44 3 


The interpreter evaluates this string, and the result (10) is returned. The substitution is performed, 
and the command is now as follows. 


set x 10 


The interpreter evaluates this string, the variable x is set to 10 , and tclsh returns 10. In partic- 
ular, note that the variable a was not defined when this command started but was defined within the 
first bracketed portion of the command. If this command had been written in another order, as in the 
following, 


set x [expr $a + [set a 3] + 4 ] 
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the Tcl interpreter would attempt to substitute the value of the variable a before assigning the value 3 
to a. 


e Ifa had not been previously defined, it would generate an error. 

e If a had been previously defined, the command would return an unexpected result depending on 
the value. For instance, if a contained an alphabetic string, expr would be unable to perform the 
arithmetic operation and would generate an error. 


A Tcl variable can contain a string that is a Tcl command string. Dealing with these commands is 
discussed in Chapter 5. 


3 DATA TYPES 
The primitive data type in Tcl is the string (which may be a numeric value). The composite data types 
are the list, dict and associative array. The Tcl interpreter manipulates some complex entities such as 
graphic objects, I/O channels, and sockets via handles. Handles are introduced briefly here, with more 
discussion in the following chapters. 

Unlike C, C++, or Java, Tcl is a typeless language. However, certain commands can define what 
sort of string data they will accept. Thus, the expr command, which performs math operations, will 
generate an error if you try to add 5 to the string “You can’t do that.” 


Assigning Values to Variables 
The command to define the value of a variable is set. It allocates space for a variable and data and 
assigns the data to that variable. 
Syntax: set varName ?value? 
Define the value of a variable. 
varName The name of the variable to define. 
value The data (value) to assign to the variable. 


set always returns the value of the variable being referenced. When set is invoked with two argu- 
ments, the first argument is the variable name and the second is a value to assign to that variable. When 
set is invoked with a single argument, the argument is a variable name and the value of that variable 
is returned. 


.—_$—_—_—_————— > 


Example 11 
% set xl 
1 
% set xX 
1 
% set z [set x 2] 
2 


% set z 


3.3 Data Types 45 


2 
% set y 
can’t read "y": no such variable 


Because Tcl is often used as a string processing language, it’s also useful to be able to add new 
characters to the end of the value in a variable. The append command will append a string to the end 
of a variable. If the variable was not previously defined, the append command will create the variable 
and will assign the initial value to the string. 


Syntax: append varName ?valuel? ?value2? 
Append one or more new values to a variable. 


varName The name of the variable to which to append the data. 
value The data to append to the variable content. 


Note that append appends only the data you request. It does not add any 
separators between data values. 


eee 
Example 12 


% set xl 


% append x 2 
12 
% append x 
12 
% append x 3 4 
1234 
% append y new value 
newvalue 


9 


.2 Strings 

The Tcl interpreter represents all data as a string within a script. (Within the interpreter, the data may 
be represented in the computer’s native format.) A Tcl string can contain alphanumeric, pure numeric, 
Boolean, or even binary data. 

Alphanumeric data can include any letter, number, or punctuation. Tcl uses 16-bit Unicode to repre- 
sent strings, which allows non-Latin characters (including Japanese, Chinese, and Korean) to be used 
in strings. A Tcl script can represent numeric data as integers, floating-point values (with a decimal 
point), hexadecimal or octal values, or scientific notation. 

You can represent a Boolean value as a | (for true) and 0 (for false), or as the string "true" or 
"yes" and "false" or "no". Any capitalization is allowed in the Boolean string: "TrUe" is recog- 
nized as a Boolean value. The command that receives a string will interpret the data as a numeric or 
alphabetic value, depending on the command’s data requirements. 
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kaa 
Example 13 


Legitimate Strings 
set alpha "“abcdefg" 


Assign the string "abcdefg" to the variable alpha. 

set validString "this is a valid string" 

Assign the string "this is a valid string" to the variable validString. 
set number 1.234 


Assign the number 1 . 234 to the variable number. 


set octalVal 0755 


Assign the octal value 755 to the variable octalVal. Commands that interpret values numer- 
ically will convert this value to 493 (base 10). Support for the leading 0 to represent octal 
numbers is still supported in Tcl 8.6, but may be removed in later releases. 


set hexVal Oxled 


Assign the hex value 1ED to the variable hexVal. Commands that interpret values numerically 
will convert this value to 493 (base 10). 


set scientificNotation 2e2 


Assign the string 2e2 to the variable sci enti ficNotation. Commands that interpret values 
numerically will convert this value to 200. 


set msg {Bad input: "Bogus". Try again.} 


Assign the string Bad input: "Bogus". Try again. tothe variable msg. Note the internal 
quotes. Quotes within a braced string are treated as ordinary characters. 


set msg "Bad input: \"Bogus\". Try again." 


Assign the string Bad input: "Bogus". Try again. to the variable msg . Note that the 
internal quotes are escaped. 


Bad Strings 
set msg "Bad input: "Bogus". Try again." 


The quotes around Bogus are not escaped and are treated as quotes. The quote before Bogus 
closes the string, and the rest of the line causes a syntax error. 


Error Message: extra characters after close-quote 


set badstring "abcdefg 


Has only one quote. The error message for this will vary, depending on how the missing quote 
is finally resolved. 


set mismatch {this is not a valid string" 


Quote and brace mismatch. The error message for this will vary, depending on how the missing 
quote is finally resolved. 
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set noquote this is not a valid string 
This set of words must be grouped to be assigned to a variable. 


Error Message: wrong # args: should be "set varName ?newValue?" = 


.3 String Processing Commands 


The string, format, and scan commands provide most of the tools a script writer needs for 
manipulating strings. The regular expression commands are discussed in Section 5.6. The string 
subcommands include commands for searching for substrings, identifying string matches, trimming 
unwanted characters, determining the contents of a string, replacing substrings and converting case. 
The format command generates formatted output from a format descriptor and a set of data (like the 
C library sprintf function). The scan command will extract data from a string and assign values to 
variables (like the C library scanf function). 

All Tcl variables are represented as strings. You can use the string manipulation commands with 
integers and floating-point numbers as easily as with alphabetic strings. When a command refers to a 
position in a string, the character positions are numbered from 0, and the last position can be referred 
to as end. 

There is more detail on all of the string subcommands in the Tcl reference and the companion 
website tutorials. The following subcommands are used in the examples in the next chapters. 

The string match command searches a target string for a match to a pattern. The pattern is 
matched using the glob match rules. The rules for glob matching are as follows. 


* Matches 0 or more characters. 
? Matches a single character. 
[] Matches a character in the set defined within the brackets. 
Labc] Defines abc as the set. 
[m-y] Defines all characters alphabetically between m and y (inclusive) as the set. 


\? Matches the single character ?. 


Note that the glob rules use [ ] in a different manner than the Tcl evaluation code. You must protect 
the brackets from tclsh evaluation, or tclsh will try to evaluate the phrase within the brackets as a 
command and will probably fail. Enclosing a glob expression in curly braces will accomplish this. 

Syntax: string match pattern string 
Returns 1 if pattern matches string, else returns 0. 
pattern The pattern to compare to string. 
string The string to match against the pattern. 


:?——_———_ $$? a —_# — 
Example 14 

% set str "This is a test, it is only a test" 

This is a test, it is only a test 

% string match "“xtestx*" $str 
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ul 
% string match "not present" $str 
0 
m7 


The string tolower command converts a string to lowercase letters. Note that this is not done in 
place. A new string of lowercase letters is returned. The string toupper command converts strings 
to uppercase using the same syntax. 


Syntax: string tolower string 


Syntax: string toupper string 
string The string to convert. 


——_—_$——-ASA AAAS aA 
Example 15 

% set upper [string toupper $str] 

THIS IS A TEST, IT IS ONLY A TEST 

% set lower [string tolower $upper] 

this is a test, it is only a test 


The string first command returns the location of the first instance of a substring in a test string, 
or —1 if the pattern does not exist in the test string. The string last returns the character location 
of the last instance of the substring in the test string. 


Syntax: string first substr string 


Syntax: string last substr string 
Return the location of the first (or last) occurrence of substrin string. 


substr The substring to search for. 


string The string to search in. 


:2—_—_§£—_AAHR_A>S_ AAA. 
Example 16 

% set str "This is a test, it is only a test" 

This is a test, it is only a test 

% set st_first [string first st $str] 

12 

% set st_last [string last st $str] 

31 

i] 


The string length command returns the number of characters in a string. With Tcl 8.0 and 
newer, strings are represented internally as 2-byte Unicode characters. The value returned by string 
length is the number of characters, not bytes. 
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Syntax: string length string 
Return the number of characters in string. 
string The string. 


———————EEEE———————— SSS SSS 
Example 17 

set len [string length $str] 

33 


The string range command returns the characters between two points in the string. 


Syntax: string range string first last 
Returns the characters in string between first and last. 


string The string. 
first The position of the first character to return 


last The position of the last character to return 


=————— 
Example 18 

% set subset [string range $str $st_first $st_last] 

st, it is only a tes 


The string map command replaces one or more substrings within a string with new values. 


Syntax: string map map string 
Return a modified string based on values in the map. 
map a set of string pairs that describe the changes to be 


made to the string. Each string pair is an o/d string 
and a new string which will replace o/d string. 


string A string to be modified. 


3—_$ A SADA. 
Example 19 

% string map {"a test" "an exam"} $str 

This is an exam, it is only an exam 

i## The map may contain multiple pairs as 

if {oldl newl old2 new2 ...} 

% string map \ 

{This These is are a {} test tests it they} $str 
These are tests, they are only tests 
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The string is command will report what type of data is in a string. It can test to see if a string 
is an integer, double, printable string, boolean and more. See the man page for all the types of tests the 
string is command can perform. 


Syntax: string is type string 
Test to see if the string matches the type. 


type The type of data that might be contained in string. 
Options include: 


digit Any unicode digit 

integer An integer value. May include leading 
or trailing whitespace. 

double A number 


alnum A letter or number 

upper Uppercase letters 

lower Lowercase letters 

space Any unicode space character 


oe 


Example 20 
% string is integer "123" 
1 
% String is integer "123a" 
0 
% String is integer "123.0" 
0 
% string is double "123.0" 
1 
% string is alnum "123a" 
1 
% string is alnum "123.0a" 
0 
i) 
The format command generates formatted strings and can perform some data conversions. It is 


equivalent to the C language sprintf command. 
Syntax: format formatString ?datal? ?data2? ... 
Return a new formatted string. 


formatString A string that defines the format of the string being 
returned. 


data# Data to substitute into the formatted string. 
The first argument must be a format description. The format description can contain text strings and 
% fields. The text string will be returned exactly as it appears in the format description. The % fields 
will be substituted with formatted strings derived from the data that follows the format descriptor. A 
literal percent symbol can be generated with a %% field. 


A 
e 
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The format for the % fields is the same as that used in the C library. The field definition is a string 
consisting of a leading percent sign, two optional fields, and a ‘formatDefinition, as follows. 


?justification? ?field width? formatDefinition 


The first character in a % field is the % symbol. 
The field justification may bea plus or minus sign. A minus sign causes the content of the 
% field to be left justified. A plus sign causes the content to be right justified. By default the data is 
right justified. 
The field width is a numeric field. If it is a single integer, it defines the width of the field in 
characters. If this value is two integers separated by a decimal point, the first integer represents the 
total width of the field in characters, and the second represents the number of digits to the right of 
the decimal point to display for floating-point formats. 

The formatDefinitionis the last character. It must be one of the following. 


S 


dori 


X or xX 


The argument should be a string. 
Replace the field with the argument. 
% format 4S Oxf 

Oxf 


The argument should be a decimal integer. 

Replace the field with the ASCII character value of this integer. 
% format %c 65 

A 


The argument should be a decimal integer. 

Replace the field with the decimal representation of this integer. 
% format %d Oxff 

255 


The argument should be an integer. 

Replace the field with the decimal representation of this integer 
treated as an unsigned value. 

% format %u -1 

4294967295 


The argument should be an decimal integer value. 

Replace the field with the octal representation of the argument. 
% format 40 Oxf 

17 


The argument should be a decimal integer. 


Replace the field with the hexadecimal representation of this integer. 


% format “x -1 
frffffttT 
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f The argument should be a numeric value. 
Replace the field with the decimal fraction representation. 
% format %3.2f 1.234 
1.23 

Eore The argument should be a numeric value. 


Replace the field with the scientific notation representation of this 
integer. 


% format Ze Oxff 
2.550000e+02 
Gor g The argument should be a numeric value. 


Replace the field with the scientific notation or floating-point 
representation. 


% format 4g 1.234e2 
123.4 


BBB] $$ $$$ 


Example 21 
% format {%5.3f} [expr 2.0/3] 
0.667 
% format {%4c%caczc%éc} 65 83 67 73 73 
ASCII 


% set def "%-12s %s" 

% puts [format $def "Author" "Title"] 

% puts [format $def "Clif Flynt" \ 
"Tcl/Tk: A Developers Guide" ] 


Author Title 
Clif Flynt Tcl/Tk: A Developers Guide 


The scan command is the flip side to format. Instead of formatting output, the scan command 
will parse a string according to a format specifier. The scan command emulates the behavior of 
the C sscanf function. The first argument must be a string to scan. The next argument is a format 
description, and the following arguments are a set of variables to receive the data values. 

Syntax: scan textString formatString ?varNamel? ... ?varNameN? 
Parse a text string into one or more variables. 
textString The text data to scan for values. 
formatString Describes the expected format for the data. The format 
descriptors are the same as for the format command. 
varName* The names of variables to receive the data. 


The scan command returns the number of percent fields that were matched. If this is not the number 
of percent fields in the formatString, it indicates that the scan command failed to parse the data. 
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The format string of the scan command uses the same % descriptors as the format command, and 
adds a few more. 
Lea] The value between the open and close square brackets will be a list of 
characters that can be accepted as matches. 


Characters can be listed as a range of characters ([a-z]). A leading or 
trailing dash is considered a character, not a range marker. 


All characters that match these values will be accepted until a 
nonmatching character is encountered. 


% scan “a scan test" {%La-z]} firstword 
1 


% set firstword 
a 


[*...] The characters after the caret (“) will be characters that cannot be 
accepted as matches. All characters that do not match these values will be 
accepted until a matching character is encountered. 


% scan “a scan test" {%[4t-z]} val 


1 
% set val 
a scan 
In the following example, the format string {%s %s %s %s} will match four sets of non-whitespace 
characters (words) separated by whitespace. 


-—$@ ———W2) Ama 
Example 22 

% set string {Speak, Friend and Enter} 

Speak, Friend and Enter 

% scan $string {%s 485 %s 4S} abcd 

4 

% puts “The Password is: $b" 

The Password is: Friend 


A format string can also include literal characters that will be included in a format return, or must 
be matched by the scan command. For instance, the scan command in the previous example could 
also be written as follows. 


% scan $string {Speak %s} password 


This would extract the password from Speak Friend and Enter, but would not extract any 
words from "The password is sesame", since the format string requires the word Speak to be the 
first word in the string. 


String and Format Command Examples 
This example shows how you might use some string, scan, and format commands to extract the 
size, from, and timestamp data from an e-mail log file entry and generate a formatted report line. 
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OOOO 
Example 23 


Script Example 
i## Define the string to parse. 
set logEntry {Mar 25 14:52:50 clif sendmail[23755]: 
from=<tcl-core-admin@lists.sourceforge.net>, 
size=35362, class=-60, nrcpts=1 


## Extract "From" using string first and string range 

set openAnglePos [string first "<" $logEntry] 

set closeAnglePos [string first ">" $logEntry] 

set fromField [string range $logEntry $openAnglePos $closeAnglePos ] 


## Extract the date using scan 
scan $logEntry {%s %d %d:%d} mon day hour minute 

if Extract the size using scan and string cmds. 

set sizeStart [string first "size=" $logEntry ] 

set substring [string range $logEntry $sizeStart end] 


i## The formatString looks for a word composed of the 
# letters ‘eisz’ (size will match) followed by an 

i## equals sign, followed by an integer. The word 

i## ‘size’ gets placed in the variable discard, 

i## and the numeric value is placed in the variable 

it sizeField. 

scan $substring {%Leisz]=%d} discard sizeField 


puts [format {%-l2s %-40s %-s} "Timestamp" "From" "Size" ] 
puts [format {%s %d %4d:%d %-40s %d} \ 
$mon $day $hour $minute $fromField $sizeField] 


Script Output 


Timestamp From Size 
Mar 25 14:52 <tcl—core—admin@lists.sourceforge.net> 35362 


[i- 2)] 
3.3.4 Lists 


A Tcl list can be represented as a string that follows some syntactic conventions. (Internally, a string is 
represented as a list of pointers to Tcl objects, which are discussed later.) 


e A list can be represented as a list of list elements enclosed within curly braces. 

e Each word is a list element. 

e A set of words may be grouped with curly braces. 

e A set of words grouped with curly braces is a list element within the larger list, and also a list in its 
own right. 

e A list element can be empty (it will be displayed as {}). 
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For example, the string {apple pear banana} can be treated as a list. The first element of this 
list is apple, the second element is pear, and so on. The order of the elements can be changed with 
Tcl commands for inserting and deleting list elements, but the Tcl interpreter will not modify the order 
of list elements as a side effect of another operation. 

A list may be arbitrarily long, and list elements may be arbitrarily long. Any string that adheres to 
these conventions can be treated as a list, but it is not guaranteed that any arbitrary string is a valid list. 
For example, "this is invalid because of an unmatched brace {" is nota valid list. 

With Tcl 8.0, lists and strings are treated differently within the interpreter. If you are dealing with 
data as a list, it is more efficient to use the list commands. If you are dealing with data as a string, it is 
better to use the string commands. 

The following are valid lists. 


{This is a six element list} 

{This list has ta sublist} in it} 

{Lists may {be nested {arbitrarily deep}}} 

"A string like this may be treated as a list" 


The following are invalid lists. 


{This list has mismatched braces 
{This list {also has mismatched braces 


2565 


3.3.5 List Processing Commands 


A list can be created in the following ways. 


e By using the set command to assign a list to a variable 

e By grouping several arguments into a single list element with the 1 ist command 

e By appending data to an unused variable with the 1 append command 

e By splitting a single argument into list elements with the sp1it command 

e By using a command that returns a list. (The array names command returns a list of associative 
array indices. It will be discussed in Section 3.3.7.) 


The 1 ist command takes several units of data and combines them into a single list. It adds whatever 
braces may be necessary to keep the list members separate. 


Syntax: list elementl ?element2? ... ?elementN? 
Creates a list in which each argument is a list element. 


element A unit of data to become part of the list 


————————EEEE—————————— SSS 
Example 24 

% set mylist [list first second [list three element sublist] fourth] 

first second {three element sublist} fourth 


The 1 append command appends new data to a list, creating and returning a new, longer list. Note 
that this command will modify the existing list, unlike the string commands, which return new data 
without changing the original. 
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Syntax: lappend JistName ?elementl? ... ?elementN? 
Appends the arguments onto a list. 
listName The name of the list to append data to. 
element A unit of data to add to the list. 


EL 
Example 25 
% lappend mylist fifth 


first second {three element sublist} fourth fifth 
= 


The sp|it command returns the input string as a list. It splits the string wherever certain characters 
appear. By default, the split location is a whi tespace character: a space, tab, or newline. 


Syntax: split data ?splitChar? 
Split data into a list. 
data The string data to split into a list. 


?splitChar? An optional character (or list of characters) at which to 
split the data. 


=—_—_—_——_ AAS A 
Example 26 
% set commaString "1,2.2,test" 
1,2.2,test 
% # Split on commas 
% set |lst2 [split $commaString ,] 


% d# Split on comma or period 
% set |lst2 [split $commaString {,.}] 


% # Split on empty space between letters 

% if (each character becomes a list element) 
% set |st2 [split $commaString {}] 

DV gee ie 2 BE OSE 


Tcl also includes several commands for manipulating lists. These include commands to convert a 
list into a string, return the number of elements in a list, search a list for elements that match a pattern, 
retrieve particular elements from a list, and insert and replace elements in a list. 

The join command converts a list into a string. 


Syntax: join Jist ?separator? 
Joins the elements of a list into a string. 
list The list to convert to a string. 


separator An optional string that will be used to separate the list 
elements. By default, this is a space. 
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The join command can be used to convert a Tcl list into a comma-delimited list for import into a 
spreadsheet. 


$B a$$ $ $i $a $@_$[?_$_$$$$$_ 


Example 27 
% set numbers [list 1 2 3 4] 
1234 
% join $numbers 
1:2:3:4 
% join $numbers ", “ 
1, 2, 3, 4 
| 
The | ]ength command returns the number of list elements in a list. Note that this is not the number 


of characters in a list, but the number of list elements. List elements may be lists themselves. These 
lists within a list are each counted as a single list element. 


Syntax: |length Jist 
Returns the length of a list. 
list The list. 


$$ $$$ $$$ 
Example 28 

% set mylist [list first second [list three element sublist] fourth] 

first second {three element sublist} fourth 

% llength $mylist 


4 
fae 


The ]search command will search a list for elements that match a pattern. The 1search com- 
mand uses the glob-matching rules by default. These are described with the previous string match 
discussion. The regular expression rules are discussed in Chapter 5. 


Syntax: lsearch ?-option? list pattern 
Returns the index of the first list element that matches pattern or -1 if no 
element matches the pattern. The first element of a list has an index of 0. 


?-option? Controls how the 1search command will behave. Multiple 
options may be used together to control the behavior of the 
lsearch command. Some of the modifiers include: 

-exact List element must exactly match the pattern. 


-glob List element must match pattern using the g1ob 
rules. This is the default matching algorithm. 

-regexp List element must match pattern using the 
regular expression rules. 
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-all Return all the values that match the pattern, 
instead of only the first element. 

-inline Return the element instead of the index of the 
element. 


-start position Return the first value after position that 
matches the pattern. 
-not Inverts the test and returns values that do not 
match the pattern. 
list The list to search. 
pattern The pattern to search for. 


$A i$ 
Example 29 

% set mylist [list first second [list three element sublist] fourth] 

first second {three element sublist} fourth 

% |search ylist second 


% i# three is not a list element - it’s a part of a list element 
% \search ylist three 


-1 

% \search ylist "threex" 

2 

% |search ylist "xoux" 

3 

% \search -all $mylist "xsx" 
0 2 


% \search -al inline $mylist "x*sx*" 

first second {three element sublist} 

% \search -start 1 -all -inline $mylist "xsx«" 
second {three element sublist} 

% \|search -not $mylist "xsx" 

3 


You can extract elements from a list with the 1 index command. 


Syntax: lindex jist index 


Returns a list element. The first element is element 0. If this value is larger 
than the list, an empty string is returned. 


list The list. 


index The position of a list entry to return. 


— 
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% set mylist [list first second [list three element sublist] fourth] 

first second {three element sublist} fourth 
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% lindex $mylist 0 

first 

% lindex $mylist 2 

three element sublist 

% lindex $mylist Llsearch $mylist xoux] 


fourth 
|__| 


The 1 insert command returns a new list with the new elements inserted. It does not modify the 
existing list. 


Syntax: linsert list position elementl ... ?elementN? 
Inserts an element into a list at a given position. 
list The list to receive new elements. 


position The position in the list at which to insert the new list 
elements. If this value is end or greater than the number of 
elements in the list, the new values are added at the end of 
the list. 


element* One or more elements to be inserted into the list. 
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% set mylist [list first second [list three element sublist] fourth] 
first second {three element sublist} fourth 

% set longerlist Llinsert $mylist 0 zero] 

zero first second {three element sublist} fourth 

% puts $mylist 

first second {three element sublist} fourth 


Like linsert, the 1replace command returns a new list. It does not modify the existing list. 
The difference between the first and ]ast elements need not match the number of elements to be 
inserted. This allows the 1 rep|1ace command to be used to increase or decrease the length of a list. 


Syntax: lreplace list first last elementl ... ?elementN? 

Replaces one or more list elements with new elements. 

list The list to have data replaced. 

first The first position in the list at which to replace elements. If 
this value is end, the last element will be replaced. If the 
value is greater than the number of elements in the list, an 
error is generated. 

last The last element to be replaced. 

element Zero or more elements to replace the elements between the 
first and Jast elements. 
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% set mylist [list first second [list three element sublist] fourth] 

first second {three element sublist} fourth 

% set newlist Llreplace $mylist 0 0 one] 

one second {three element sublist} fourth 

% set shortlist Llreplace $mylist 0 1] 

{three element sublist} fourth 


The next example demonstrates using the list commands to split a set of comma and newline delim- 
ited data (a common export format for spreadsheet programs) into a Tcl list and then reformat the data 
for display. 
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List Commands Example 
it Define the raw data 


set rawData {Package,Major,Minor, Patch 
Tcl1,8,6,0 

math::geometry,1,0,3 

math: :complexnumbers,1,0, 2} 


## Split the raw data into a list using the newlines 
if as list element separators. 

d## This creates a list in which each line becomes a 
# list element 

set dataList [split $rawData "\n"] 


## Create a list of the column headers. 
set columns [split [lindex $dataList 0] ","] 


foreach line [lrange $dataList 1 end] { 
## Convert the line of data into a list 
set rowValues [split $line ","]\ 


## Create a new list from $rowValues that includes 
## all the elements after the first (package name). 
set revList [lrange $rowValues 1 end] 


d## and rejoin them into a "." separated string 
set revision [join $revList "."] 


d## Display a reformatted version of the data line 
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puts [format "%s: %S Revision: %s" [lindex $columns 0]\ 
[lindex $rowValues 0] $revision] 


Script Output 


Package: Tcl Revision: 8.6.0 
Package: math::geometry Revision: 1.0.3 
Package: math::complexnumbers Revision: 1.0.2 


3.3.6 Dictionaries 
The dict command was added to Tcl in version 8.5. Conceptually, a dictionary is an ordered list of 
key-value pairs. A dict looks like this: 


puts [dict create keyl vall key2 val2] 
keyl vall key2 val2 


The concept of key-value pairs is simple enough that you may be tempted to just write procedures 
to handle such lists. Writing procedures to handle lists of key-value pairs will be demonstrated in 
Chapter 6. 

Unless you are constrained to use versions of Tcl that don’t have dictionary support, you should use 
the dict command. The improvements of the dictionary over home-grown keyed-list procedures are: 


e the dict supports nesting dictionaries within a dictionary (just as lists can be nested). 

e the dict command is implemented in fast C code with hash tables. 

e there is a rich set of dict subcommands to search and manipulate dictionaries. 

e the dict command contains both field and value information, making it useful as a data construct 
to use with a database extension. 


As with Tcl lists, a dict variable can be initialized in several ways including dict create, dict 
append and dict lappend. 

The dict create command creates a complete dictionary without assigning the value to a 
variable, just as you might use the format command to initialize a string. 


Syntax: dict create keyl vall key2 val2 
Create a dictionary of keys and values. 


keyx A key in the dictionary. 


val* The value to associate with the previous key. 


The next example creates a dictionary of movie titles and notable quotes. If you print the contents 
of the $quotes variable it will look just like a list of movie titles and quotes. 
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Creating a Dict 
set quotes [dict create \ 
"Casablanca" "Play it, Sam." \ 
"Star Wars" "I get a bad feeling about this.” \ 
"Indiana Jones" "Snakes, Why did it have to be snakes." \ 
"Looney Tunes" "What’s Up Doc?"] 


set movie Casablanca 
puts "A notable quote from $movie is: [dict get $quotes $movie]" 


Script Output 
A notable quote from Casablanca is: Play it, Sam. 
= 
In the previous example, the values associated with each key are a grouped set of words, but there 
is no higher level of grouping. If we want each quote to be a single unit (so we can have multiple 
quotes for some movies), the dict create command will need to add the grouping as shown in the 
next example. 
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Creating a Dict of Quotes 
set quotes [dict create \ 
"Casablanca" [list "Play it, Sam." "Round up the usual suspects"] \ 
"Star Wars" [list "I get a bad feeling about this."] \ 
"Indiana Jones" [list "Snakes, Why did it have to be snakes."]] 


set movie Casablanca 
puts "A notable quote from $movie is: \ 
Llindex [dict get $quotes $movie] 0]" 


Script Output 


A notable quote from Casablanca is: Play it, Sam. 


The dict append and dict lappend commands will modify an existing dict variable, or create 
a new variable if the variable did not previously exist. This is the same way that the append and 
lappend commands work with string and list variables 


Syntax: dict append dictName key value 
Appends the given value to the given key. 
dictName Name of the variable to be modified. 
key Key within this dictionary to be modified. 


value Value to append onto the current value of this key. 
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Syntax: dict lappend dictName key value 
Appends the given value to the given key. 
dictName Name of the variable to be modified. 
key Key within this dictionary to be modified. 


value Value to lappend onto the current value of this key. 
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Modifying a Dict 


if Add a new quote to the Star Wars quotes 
dict lappend quotes "Star Wars" "Feel the Force, Luke." 


i## Create a new entry for ET quotes. 
dict lappend quotes "ET" "E.T. Phone Home." 


set movie "Star Wars" 

puts "Notable quotes from $movie include:" 

foreach quote [dict get $quotes $movie] { 
puts "  $quote" 

} 


Script Output 


Notable quotes from Star Wars include: 
I get a bad feeling about this. 
Feel the Force, Luke. 


Because the values in this dictionary are lists, modifying an individual list element must be done 
by extracting the value from the dictionary, modifying it and replacing it. For example, the complete 
Casablanca quote is “Play it, Sam. Play As Time Goes By.” 


The dict replace command will let us replace a value with a new value. Like the ]replace 


command, this command does not replace the value in the dictionary, it returns a new dictionary with 
the value modified. 


Syntax: dict replace $dict key new_value 
Return a new dictionary with the value associated with a key replaced with 
a new value. 
$dict The dictionary to be modified. 
key The key to be modified. 
new_value The new value for this key. 
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Modifying a Dict Value 


set vals [dict get $quotes Casablanca] 

set val [lindex $vals 0] 

append val " Play ‘As Time Goes By’." 

set vals [lreplace $vals 0 0 $val] 

set quotes [dict replace $quotes Casablanca $vals] 


set movie Casablanca 
puts "The full quote from $movie is: \ 
Llindex [dict get $quotes $movie] 0]" 


Script Output 


The full quote from Casablanca is: 
Play it, Sam. Play ‘As Time Goes By’. 


A dictionary value can be modified in place with the dict set command. 


Syntax: dict set dictName key new_value 
Sets the contents of a dictionary key to a new value. 
$dict The name of the dictionary to be modified. 
key The key to be modified. 


new_value The new value for this key. 


The previous example—adding a string to one movie quote—becomes a bit simpler by using the 
dict set command instead of dict replace. 
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Modify a Dict Value 


set vals [dict get $quotes Casablanca] 
set val [lindex $vals 0] 

append val " Play ‘As Time Goes By’." 
set vals [lreplace $vals 0 0 $val] 
dict set quotes Casablanca $vals 


set movie Casablanca 
puts "The full quote from $movie is: \ 
Llindex [dict get $quotes $movie] 0]" 


Script Output 


The full quote from Casablanca is: 
Play it, Sam. Play ‘As Time Goes By’. 
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.] Associative Arrays 

The associative array is an array that uses a string to index the array elements, instead of a numeric 
index the way C, FORTRAN, and BASIC implement arrays. A variable is denoted as an associative 
array by placing an index within parentheses after the variable name. 

For example, price(apple) and price(pear) would be associative array variables that could 
contain the price of an apple or pear. The associative array is a powerful construct in its own right and 
can be used to implement composite data types resembling the C struct or even a C++ class object. 
Using associative arrays is further explored in Chapter 6. 


1] $$ $$ 


ee 


Example 39 

set price(apple) .10 price is an associative array. The element referenced by the 
index apple is set to .10. 

set price(pear) .15 price is an associative array. The element referenced by the 
index pear is set to .15. 

set quantity(apple) 20 quantity is an associative array. The element referenced by 
the index app|e is set to 20. 

set discount(12) 0.95 discount is an associative array. The element referenced by 


the index 12 is set to 0.95. . 


Associative Array Commands 


An array element can be treated as a simple Tcl variable. It can contain a number, string, list, or even the 
name of another array element. As with lists, there is a set of commands for manipulating associative 
arrays. You can get a list of the array indices, get a list of array indices and values, or assign many 
array indices and values in a single command. Like the string commands, the array commands are 
arranged as a set of subcommands of the array command. 

The list of indices returned by the array names command can be used to iterate through the 
content of an array. 


Syntax: array names arrayName ?pattern? 
Returns a list of the indices used in this array. 


arrayName The name of the array. 


pattern If this option is present, array names will return only 
indices that match the pattern. Otherwise, array names 
returns all the array indices. 


$$ $$ 
Example 40 
set fruit(apples) 10 
set fruit(pears) 5 
foreach item [array names fruit *] { 
puts "There are $fruit($item) $item." 
} 
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There are 5 pears. 
There are 10 apples. 


The array get command returns the array indices and associated values as a list. The list is a set 
of pairs in which the first item is an array index and the second is the associated value. The third list 
element will be another array index (first item in the next pair), the fourth will be the value associated 
with this index, and so on. 


Syntax: array get arrayName 
Returns a list of the indices and values used in this associative array. 
arrayName The name of the array. 


= eee 
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% array get fruit 

pears 5 apples 10 


The array set command accepts a list of values in the format that array get generates. The 
array get and array set pair of commands can be used to copy one array to another, save and 
restore arrays from files, and so on. 


Syntax: array set arrayName {indexl valuel ... indexN valueN} 
Assigns each value to the appropriate array index. 
arrayName The name of the array. 
index* An index in the array to assign a value to. 


valuex The value to assign to an array index. 


———— 
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% array set fruit [list bananas 20 peaches 40] 

% array get fruit 


bananas 20 pears 5 peaches 40 apples 10 
zl 


The next example shows some simple uses of an array. Note that while the Tcl array does not 
explicitly support multiple dimensions the index is a string and you can define multidimensional arrays 
by using a naming convention, such as separating fields with a comma, period, dash, and so on, that 
does not otherwise appear in the index values. 


$$ $$ 
Example 43 
Array Example 

dt Initialize some values with set 

set fruit(apple.cost) .10 

set fruit(apple.count) 5 
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if Initialize some more with array set 
array set fruit {pear.cost .15 pear.count 3} 
## At this point the array contains: 


if Index Value 
Ht apple.cost  .10 
# pear.cost ahd 


## apple.count 5 
dt pear.count 3 


i## Count the number of different types of fruit in the 
# array by getting a list of unique indices, and then 

## using the llength command to count the number of 

## elements in the list. 

set typeCount [llength [array names fruit xcost]] 

puts "There are $typeCount types of fruit in the fruit array" 
i## You can use another variable to hold all, 

## or a part of an array index. 
set type apple 
puts "There are $fruit($type.count) apples" 
set type pear 
puts "There are $fruit($type.count) pears" 
array set new [array get fruit] 
set type pear 
puts "There are $new($type.count) pears in the new array" 


Script Output 
There are 2 types of fruit in the fruit array 
There are 5 apples 
There are 3 pears 
There are 3 pears in the new array 


= 
3.3.9 Binary Data 
Versions of Tcl prior to 8.0 (pre 1998) used null-terminated ASCII strings for the internal data repre- 
sentation. This made it impossible to use Tcl with binary data that might have NULLs embedded in the 
data stream. 

With version 8.0, Tcl moved to a new internal data representation that uses a native-mode data 
representation. An integer value is saved as a long integer, a real value is saved as an IEEE floating 
point value, and so on. The new method of data representation supports binary data, and a command 
was added to convert binary data to integers, floats, or strings. Tcl is still oriented around printable 
ASCII strings but the binary command makes it possible to handle binary data easily. 

The binary command supports two subcommands to convert data to and from a binary repre- 
sentation. The format subcommand will transform an ASCII string to a binary value, and the scan 
subcommand will convert a string of binary data to one or more printable Tcl variables. These sub- 
commands require a descriptor to define the format of the binary data. Examples of these descriptors 
follow the command syntax. 
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Syntax: binary format format argl ?arg2? ... ?argN? 
Returns a binary string created by converting one or more printable ASCII strings to 
binary format. 
format A string that describes the format of the ASCII data. 


arg* The printable ASCII to convert. 


Syntax: binary scan binaryData format argl ?varNamel? ... 
?varNameN? 
Converts a string of binary data to one or more printable ASCII strings. 
binaryData The binary data. 


format A string that describes the format of the ASCII data. 


varNamex Names of variables to accept the printable 
representation of the binary data. 
The components of format are similar to the format strings used by scan and format in that they 
consist of a descriptor (a letter) and an optional count. If the count is defined, it describes the number 


of items of the previous type to convert. The count defaults to 1. Common descriptors include the 
following. 
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Script Example 
binary scan "Tk" H4 x 
puts "X: $x" 
if Assign three integer values to variables 
set a 1415801888 
set b 1769152615 
set c 1919246708 
## Convert the integers to ASCII equivalent 
puts [binary format {I 12} $a [list $b $c]] 


Script Output 
X: 546b 
Tcl is great 


= 
The string used to define the format of the binary data is very powerful, and allows a script to 
extract fields from complex C structures. 
h Converts between binary and hexadecimal digits in little endian order. 
binary format h2 34 - returns “C” (0x43). 
binary scan "4" h2 x - stores 0x43 in the variable x 
H_ Converts between binary and hexadecimal digits in big endian order. 
binary format H2 34 - returns “4” (0x34). 
binary scan "4" H2 x - stores 0x34 in the variable x 
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c Converts an 8-bit value to/from ASCII. 

ary format c 0x34 - returns “4” (0x34). 

inary scan "4" c x - stores 0x34 in the variable x 

nverts a 16-bit value to/from ASCII in little endian order. 

ary format s 0x3435 - returns “54” (0x35 0x34). 

ary scan "45" s x - stores 13620 (0x3534) in the variable x 

nverts a 16-bit value to/from ASCII in big endian order. 

ary format S 0x3435 - returns ”45” (0x34 0x35). 

ary scan "45" S x - stores 13365 (0x3435) in the variable x 

nverts a 32-bit value to/from ASCII in little endian order. 

ary format i 0x34353637 - returns ’7654” (0x37 0x36 0x35 0x34). 
ary scan "7654" ix - stores 875902519 (0x34353637) in the variable x 
I Converts a 32-bit value to/from ASCII in big endian order. 

binary format I 0x34353637 - returns ’4567” (0x34 0x35 0x36 0x37). 
binary scan "7654" Ix - stores 926299444 (0x37363534) in the variable x 
f Converts 32-bit floating point values to/from ASCII. 

binary format f 1.0 - returns the binary string ’Ox00803f’. 

binary scan "Ox00803f" f x -stores 1.0 in the variable x 
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Example 45 
Script Examples 
C Code to Generate a Structure Tcl Code to Read the Structure 
#include <stdio.h> ## Open the input file, and read data 
#Finclude <fcntl.h> set if [open tstStruct r] 
main () { set d [read $if] 
struct a { close $if 
int i; 
float f[2]; ## scan the binary data into variables. 
char s[20]; 
} aa; binary scan $d "i f2 ax" i f s 
FILE xof; i## The string data includes any binary 
## garbage after the NULL byte. 
aa.i = 100; # Strip off that junk. 
aa.f[0] = 2.5; 
aaerld=.3..8% set Opos [string first\ 


[binary format c 0x00] $s] 
strcpy(aa.s, "This is a test"); incr Opos -1 


set s [string range $s 0 $0pos] 
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of = fopen("tstStruct", "w"); 


fwrite(sizeof(aa), 1, of); it Display the results 
fclose(of); puts $i 
} puts $f 
puts $s 
Script Output 


100 
2.5 3.79999995232 
This is a test 


3.3.10 Handles 
Tcl uses handles to refer to certain special-purpose objects. These handles are returned by the Tcl 
command that creates the object and can be used to access and manipulate the object. When you open 
a file, a handle is returned for accessing that file. The graphic objects created by a wish script are 
also accessed via handles, which will be discussed in the wish tutorial. The following are types of 
handles. 
channel A handle that references an I/O device such as a file, serial port, or TCP 
socket. A channel is returned by an open or socket call and can be 
an argument toaputs, read, close, flush, orgets call. 


graphic A handle that refers to a graphic object created by a wi sh command. 
This handle is used to modify or query an object. 


http A handle that references data returned by an http: : getur1 operation. 
An http handle can be used to access the data that was returned from 
the http: :geturl command or otherwise manipulate the data. 
There will be detailed discussion of the commands to manipulate handles in sections that discuss 
that type of handle. 


3.4 ARITHMETIC AND BOOLEAN OPERATIONS 


The commands discussed so far directly manipulate particular types of data. Tcl also has a rich set 
of commands for performing arithmetic and Boolean operations and for using the results of those 
operations to control program flow. 


Math Operations 


Math operations are performed using the expr and incr commands. The expr command provides an 
interface to a general-purpose calculation engine, and the incr command provides a fast method of 
changing the value of an integer. 

The expr command will perform arbitrarily complex math operations. Unlike most Tcl commands, 
expr does not expect a fixed number of arguments. It can be invoked with the arguments grouped as 
a string or as individual values and operators. The expr command is optimized to handle arithmetic 
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strings. You will see a performance improvement if you pass the expr command a string enclosed in 
curly braces, rather than using quotes which pushes some processing into the Tcl interpreter, instead of 
the expr command code. 

The arithmetic arguments to expr may be grouped with parentheses to control the order of math 
operations. The expr command can also evaluate Boolean expressions and is used to test conditions 
by the Tcl branching and looping commands. 


Syntax: expr mathExpression 


Tcl supports the following math operations (grouped in decreasing order of precedence). 


—-+~! Unary minus, unary plus, bitwise NOT, logical NOT. 

* /% Multiply, divide, modulo (return the remainder). 

+ — Add, subtract. 

<> Left shift, right shift. 

<><=>= _ Less than, greater than, less than or equal, greater than or equal. 

i Equality, inequality. 

& Bitwise AND. 

s Bitwise exclusive OR. 

| Bitwise OR. 

&E& Logical AND. Produces a | result if both operands are nonzero; 0 
otherwise. 

| Logical OR. Produces a 0 result if both operands are zero; | 
otherwise. 

X?y:Z If-then-else, as in C. If x evaluates to nonzero, the result is the value 


of y. Otherwise, the result is the value of z. The x operand must 
have a numeric value. The y and z operands may be variables or Tcl 
commands. 
Note that the bitwise operations are valid only if the arguments are integers (not floating-point or 
scientific notation). The expr command also supports the following math functions and conversions. 


Trigonometric Functions 
sin Sin(radians) 


set sin [expr sin($degrees/57.32) ] 


cosine cos (radians) 

set cosine [expr cos(3.14/2)] 
tangent tan (radians) 

set tan [expr tan($degrees/57.32)] 
arcsin asin (float) 


set angle [expr asin(.7071)] 
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arccosine ac 
se 
arctangent at 
se 


hyperbolic sin si 
hyperbolic cosine co 


hyperbolic tangent ta 
se 
hypotenuse hy 
se 
arctangent of ratio at 


se 


Exponential Functions 


os (float) 

t angle [expr acos(./071)] 

an (float) 

t angle [expr atan(.7071)] 

nh (radians) 

t hyp_sin [expr cosh(3.14/2)] 
sh (radians) 
t hyp_cos [expr cosh(3.14/2)] 
nh (radians) 
t hyp_tan Lexpr tanh(3.14/2)] 
pot (float, float) 

t len [expr hypot($sidel, $side2)] 

an2 (float, float) 

t radians [expr atan2($numerator, $denom) ] 


naturallog log (float) 


set two 


[expr log(7.389)] 


log base 10 =10g10 (float) 


set two 


[expr 1o0g10(100)] 


square root sqrt (float) 


set two 


exponential exp (float) 


[expr sqrt(4)] 


set seven [expr exp(1.946) ] 


power pow (float, float) 


set eigh 


Conversion Functions 
Return closest int 


t Lexpr pow(2, 3)] 


round (float) 
set duration [expr round($distance / $speed)] 


Largest integer less than a_ floor (float) 


float 


set overpay [expr ceil($cost / $count) ] 


Smallest integer greater than ceil (float) 


a float 


set each [expr ceil($cost/$count) J 


Floating Point remainder fmod(float, float) 


set missing [expr fmod($cost, $each) ] 
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Convert int to float double (int) 

set average [expr $total / double($count) ] 
Convert float to int int (float), 

set leastTen [expr (int($total) / 10) * 10] 
Absolute Value abs (num) 


set xDistance [expr abs($xl - $x2)] 


Random Numbers 
Seed random number srand (int) 


expr srand(£Lclock seconds]) 
Generate random number rand() 
set randomFloat [expr rand() ] 


a 
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% set card Lexpr rand()] 

0.557692307692 

% set cardNum Lexpr int($card * 52)] 

29 

% set cardSuit Lexpr int($cardNum / 13)] 


% set cardValue [expr int($cardNum % 13)] 


% expr floor(sin(3.14/2) * 10) 
0 


% set x [expr int(rand() * 10)] 


% expr atan(((3 + $x) * $x)/100.) 
0.273008703087 
| 


The incr command provides a shortcut to modify the content of a variable that contains an integer 
value. The incr command adds a value to the current content of a given variable. The value may be 
positive or negative, thus allowing the incr command to perform a decrement operation. The incr 
command is used primarily to adjust loop variables. 


Syntax: incr varName ?incrValue? 
incr Add a value (default 1) to a variable. 
varName The name of the variable to increment. 
NOTE: This is a variable name, not a value. Do not start 


the name with a $. This variable must contain an integer 
value, not a floating-point value. 

?incrValue? The value to increment the variable by. May be a positive 
or negative number. The value must be an integer between 
—65,536 and 65,535, not a floating-point value. 
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Example 47 
% set x 4 
4 
% incr xX 
5 
% incr x -3 
2 
% set y Lincr x] 
3 
% puts "x: $x y: $y" 
Xe Br Ve. 8 


3.4.2 Conditionals 

The if Command 

Tcl supports both a single-choice conditional (i f) and a multiple-choice conditional (switch). The 3 f 
command tests a condition, and if that condition is true, the script associated with this test is evaluated. 
If the condition is not true, an alternate choice is considered, or alternate script is evaluated. 


Syntax: if {testExpressionl} { 

body1 

} 2elseif {testExpression2} { 

body2 

}? ?else { 

bodyN 

}? 

if Determine whether a code body should be evaluated 

based on the results of a test. If the test returns true, 
the first body is evaluated. If the test is false and a 
body of code exists after the else, that code will be 
evaluated. 


testExpressionl If this expression evaluates to true, the first body of 
code is evaluated. The expression must be in a form 
acceptable to the expr command. These forms 
include the following. 


An arithmetic comparison 

{$a < 2}. 
A string comparison 

{ $string ne "OK"}. 
The results of a command 

{ Leof $inputFilel]}. 
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A variable with a numeric value. 


Zero (0) is considered false, and nonzero values 


are true. 

bodyl The body of code to evaluate if the first test evaluates 
as true. 

elseif If testExpression1] is false, evaluate 


testExpressioned. 
testExpression2 A second test to evaluate if the first test evaluates to 


false. 

body2 The body of code to evaluate if the second test 
evaluates as true. 

2?else bodyN? If all tests evaluate false, this body of code will be 
evaluated. 


In the following example, note the placement of the curly braces ({}). The Tcl Style Guide describes 
the preferred format for if, for, proc, and while commands. It recommends that you place the 
left curly brace of the body of these commands on the line with the command and place the body on 
the next lines, indented two spaces. The final, right curly brace should go on a line by itself, indented 
even with the opening command. This makes the code less dense (and more easily read). 

Putting the test and action on a single line is syntactically correct Tcl code but can cause mainte- 
nance problems later. You will need to make some multiline choice statements, and mixing multiline 
and single-line commands can make the action statements difficult to find. Also, what looks simple 
when you start writing some code may need to be expanded as you discover more about the problem 
you are solving. It is recommended practice to lay out your code to support adding new lines of code. 

A Tcl command is normally terminated by a newline character. Thus, a left curly brace must be at 
the end of a line of code, not on a line by itself. Alternatively, you can write code with the new line 
escaped, and the opening curly brace on a new line, but this style makes code difficult to maintain. 


7———_——_a_ 
Example 48 
A Simple Test 
set x 2 
set y 3 
if {$x < $y} { 
puts "x is less than y" 


} 


Script Output 


x is less than y 


The switch Command 

The switch command allows a Tcl script to choose one of several patterns. The switch command 
is given a variable to test and several patterns. The first pattern that matches the test phrase will be 
evaluated, and all other sets of code will not be evaluated. 
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Syntax: switch ?opt? str patl bodl ?pat2 bod2 ...? ?default defaultBody? 
Evaluate 1 of N possible code bodies, depending on the value of a string. 
?opt? One of the following possible options. 
-exact Matcha pattern string exactly to the test string, 
including a possible "-" character. 
-glob Match a pattern string to the test string using 
the g1ob string match rules. These are the 
default matching rules. 


-regexp Match a pattern string to the test string using 
the regular expression string match rules. 


-- Absolutely the last option. The next string will 
be the string argument. This allows strings that 
start with a dash (-) to be used as arguments 
without being interpreted as options. 


str The string to match against patterns. 

patN A pattern to compare with the string. 

bodN A code body to evaluate if patN matches string. 

default A pattern that will match if no other patterns have 
matched. 


defaultBody The script to evaluate if no other patterns were matched. 


The options -exact, -glob, and -regexp control how the string and pattern will be com- 
pared. By default, the swi tch command matches the patterns using the glob rules described previously 
with string match. 

You can use regular expression match rules by including the - regexp flag. The regular expression 
rules are similar in that they allow you to define a pattern of characters in a string but are more complex 
and more powerful. The regexp command, which is used to evaluate regular expressions, is discussed 
in Chapter 5. The switch command can also be written with curly braces around the patterns and 
body. 


Syntax: switch ?option? string { 
patternl bodyl 
?pattern2 body2? 
?default defaultBody? 


When the switch command is used without braces (as shown in the first switch statement below 
that follows), the pattern strings may be variables, allowing a script to modify the behavior of a 
Switch command at runtime. When the braces are used (the second example following), the pattern 
strings must be hard-coded patterns. 
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eer 
Example 49 


Script Example 
set x 7 
set y 7 
if Using no braces substitution occurs before the switch 
i## command looks for matches. 
i## Thus a variable can be used as a match pattern: 


switch $x \ 

y {puts "X=Y"} \ 
{[0-9]} {puts "< 10"} \ 
default {puts "> 10"} 


i## With braces, the $y is not substituted to 7, and switch looks 
# for a match to the literal string $y 


switch -glob $x { 
"1" {puts "one" 
"2" {puts "two"} 
"3" {puts "three"} 
"$y" {puts "X=Y"} 
{[4-9]} {puts "greater than 3"} 
default {puts "Not a value between 1 and 9"} 


Script Output 
X=Y 
greater than 3 


If you wish to evaluate the same script when more than one pattern is matched, you can use a dash 
(- ) in place of the body to cause the switch command to evaluate the next body, instead of the body 
associated with the current pattern. Part of a folk music quiz might resemble the following. 


————————————— eee eee 
Example 50 


Script Example 

puts "Who recorded ‘Mr Tambourine Man’ 
gets stdin artist ;# User types Bob Dylan 
switch $artist { 

{Bob Dylan} - 

{Judy Collins} - 

{Glen Campbell} - 

{William Shatner} - 

{The Chipmunks} - 

{The Byrds} { 


78 CHAPTER 3 Introduction to the Tcl Language 


puts "$artist recorded ‘Mr Tambourine Man’ " 


} 
default { 


puts "$artist probably recorded ‘Mr Tambourine Man’ " 


} 


Script Output 
Who recorded ‘Mr Tambourine Man’ 
Bob Dylan 
Bob Dylan recorded ‘Mr Tambourine Man’ 


Looping 
Tcl provides commands that allow a script to loop on a counter, loop on a condition, or loop through 
the items in a list. These three commands are as follows. 

for A numeric loop command 

while A conditional loop command 


foreach A list-oriented loop command 


The f or Command 
The for command is the numeric loop command. 


Syntax: for start test next body 
Set initial conditions and loop until the test fails. 
start Tcl statements that define the start conditions for the loop. 


test A statement that tests an end condition. This statement must be in 
a format acceptable to expr. 


next A Tcl statement that will be evaluated after each pass through the 
loop. Normally this increments a counter. 


body The body of code to evaluate on each pass through the loop. 


The for command is similar to the looping for in C, FORTRAN, BASIC, and others. The for 
command requires four arguments; the first ( start ) sets the initial conditions, the next ( test ) tests 
the condition, and the third ( next ) modifies the state of the test. The last argument ( body ) is the 
body of code to evaluate while the test returns true. 


eee 
Example 51 
Script Example 
for {set i O} {$i < 2} {incr i} { 
puts "I is: $i" 
} 
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Script Output 
I is: 0 
I is: 1 


The while Command 
The whi 1e command is used to loop until a test condition becomes false. 
Syntax: while test body 
Loop until a condition becomes false. 
test A statement that tests an end condition. This statement must be in a 
format acceptable to expr. 


body The body of code to evaluate on each pass through the loop. 


:—@@éom o£ pm 
Example 52 
While Loop Example 
set x 0; 
while {$x < 5} { 
set x Lexpr $x+$x+1] 


puts "X: $x" 
} 
Script Output 
X: 1 
X: 3 
X: 7 


The foreach Command 
The foreach command is used to iterate through a list of items. 


Syntax: foreach JistVar list body 
Evaluate body for each of the items in ] 7st. 
listVar This variable will be assigned the value of the list element 
currently being processed. 
list A list of data to step through. 


body The body of code to evaluate on each pass through the loop. 


a 
Example 53 
Script Example 
set total 0 
foreach num {1 2 3 4 5} { 
set total [expr $total + $num] 


} 
puts "The total is: $total" 
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Script Output 


The total is: 15 


With Tcl release 7.5 (1996) and later, the foreach command was extended to handle multiple sets 
of list variables and list data. 
Syntax: foreach valueListl dataListl ?valueList2 dataList2?... { 
body 
} 


If the va7ueLi7st contains more than one variable name, the Tcl interpreter will take enough values 
from the dataList to assign a value to each variable on each pass. If the dataList does not contain 
an even multiple of the number of va] ueList elements, the variables will be assigned an empty string. 


$A 
Example 54 
Script Example 
foreach {pres date} { {George Washington} {1789-1797} 
{John Adams} {1797-1801} 
{Thomas Jefferson} {1801-1809} 
{James Madison} {1809-1817} 
{James Monroe} {1817-1825} 
} state {Virginia Massachusetts Virginia Virginia Virginia} { 
puts "$pres was from $state and served from $date" 


} 


Script Output 
George Washington was from Virginia and served from 1789-1797 
John Adams was from Massachusetts and served from 1797-1801 
Thomas Jefferson was from Virginia and served from 1801-1809 
James Madison was from Virginia and served from 1809-1817 
James Monroe was from Virginia and served from 1817-1825 


Exception Handling in Tcl 

When the Tcl interpreter hits an exception condition the default action is to halt the execution of the 
script and display the data in the errorInfo global variable. The information in errorInfo will 
describe the command that failed and will include a stack dump for all the procedures that were in 
process when this failure occurred. The simplest method of modifying this behavior is to use the 
catch command to intercept the exception condition before the default error handler is invoked. 


Syntax: catch script ?varName? 
Catch an error condition and return the results rather than aborting the 
script. 
script The Tcl script to evaluate. 


varName_ Variable to receive the results of the script. 
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The catch command catches an error in a script and returns a success or failure code rather than 
aborting the program and displaying the error conditions. If the script runs without errors, catch 
returns 0. If there is an error, catch returns 1, and the errorCode and errorInfo variables are set 
to describe the error. 

Sometimes a program should generate an exception. For instance, while checking the validity of 
user-provided data, you may want to abort processing if the data is obviously invalid. The Tcl command 
for generating an exception is error. 


Syntax: error informationalString ?Info? ?Code? 


error Generate an error condition. If not caught, 
display the informationalString and stack 
trace and abort the script evaluation. 


informationalString Information about the error condition. 


Info A string to initialize the errorInfo string. 
Note that the Tcl interpreter may append more 
information about the error to this string. 


Code A machine-readable description of the error 
that occurred. This will be saved in the global 
errorCode variable. 


The next example shows some ways of using the catch and error commands. 


$$ 
Example 55 
Script Example 
proc errorProc {first second} { 

global errorInfo 

## $fail will be non-zero if $first is non-numeric. 

set fail [catch {expr 5 « $first} result] 

# if $fail is set, generate an error 

if {$fail} { 
Bad first argument" 


# This will fail if $second is non-numeric or 0 
set fail [catch {expr $first/$second} dummy] 
if {$fail} { 
error "Bad second argument" \ 
"second argument fails math test\cback n\$errorInfo 


} 


error “errorProc always fails evaluating error" \ 
[list USER {123} {Non-Standard User—Defined Error}] 


wow 


} 
## Example Script 


puts "call errorProc with a bad first argument" 
set fail [catch {errorProc X 0} returnString] 
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if {$fail} { 
puts "Failed in errorProc" 
puts "Return string: $returnString" 
puts “Error Info: $errorInfo\n" 
} 
puts "call errorProc with a 0 second argument" 
if {[catch {errorProc 1 O} returnString]} { 
puts "Failed in errorProc" 
puts "Return string: $returnString" 
puts "Error Info: $errorInfo\n" 
} 
puts "call errorProc with valid arguments" 
set fail [catch {errorProc 1 1} returnString] 
if {$fail} { 
if {[string first USER $errorCode] == 0} { 

puts "errorProc failed as expected" 

puts "returnString is: $returnString" 

puts “errorInfo: $errorInfo" 
} else { 

puts "errorProc failed for an unknown reason" 


Script Output 
call errorProc with a bad first argument 
Failed in errorProc 
Return string: Bad first argument 
Error Info: Bad first argument 
while executing 
"error "Bad first argument"" 
(procedure "errorProc" line 10) 
invoked from within 
"errorProc X 0" 
call errorProc with a 0 second argument 
Failed in errorProc 
Return string: Bad second argument 
Error Info: second argument fails math test 
divide by zero 
while executing 
"expr \$first/\$second" 
(procedure "errorProc" line 15) 
invoked from within 
"errorProc 1 0" 
call errorProc with valid arguments 
errorProc failed as expected 
returnString is: errorProc always fails 
erroriInfo: evaluating error 
(procedure "errorProc" line 1) 
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invoked from within} 
"errorProc 1 1" 


Note the differences in the stack trace returned in errorInfo in the error returns. The first, gener- 
ated with error message, includes the error command in the trace, whereas the second, generated 
with error message Info, does not. 

If there is an Info argument to the error command, this string is used to initialize the error - 
Info variable. If this variable is not present, Tcl uses the default initialization, which is a description 
of the command that generated the exception. In this case, that is the error command. If your appli- 
cation needs to include information that is already in the errorInfo variable, you can append that 
information by including $errorInfo in your message, as done with the second test. 

The errorInfo variable contains what should be human-readable text to help a developer debug a 
program. The errorCode variable contains a machine-readable description to enable a script to handle 
exceptions intelligently. The errorCode data is a list in which the first field identifies the class of error 
(ARITH, CHILDKILLED, POSIX, and so on), and the other fields contain data related to this error. 
The gory details are in the on-line manual/help pages under tcl vars. 

If you are used to Java, you are already familiar with the concept of separating data returns from 
status returns. If your background is C/FORTRAN/BASIC type programming, you are probably more 
familiar with the C/FORTRAN paradigm of returning status as a function return, or using special values 
to distinguish valid data from error returns. For example, the C library routines return a valid pointer 
when successful, and a NULL pointer for failure. 

If you want to use function return values to return status in Tcl, you can. Using the error com- 
mand (particularly in low-level procedures that application programs will invoke) provides a better 
mechanism. The following are reasons for using error instead of status returns. 

e An application programmer must check a procedure status return. It is easy to forget to check a 
status return and miss an exception. It takes extra code (the catch command) to ignore bad status 
generated by error. 

e This makes the fast and dirty techniques for writing code (not checking for status, or not catching 
errors) the more robust technique. If a low-level procedure has a failure, the intermediate code 
must propagate the failure to the top level. Doing this with status returns requires special code to 
propagate the error, which means all functions must adhere to the error-handling policy. 

e The error command automatically propagates the error. Procedures that use a function that may 
fail need not include exception propagation code. This moves the policy decisions for how to handle 
an exception to the application level, where it is more appropriate. 


3.5 MODULARIZATION 


Tcl has support for all modern software modularization techniques. 


Ww 


e Subroutines (with the proc command) 
e Multiple source files (with the source command) 
e Libraries (with the package command) 


The package commands are discussed in detail in Chapter 8. 


84 CHAPTER 3 Introduction to the Tcl Language 


3.5.1 Procedures 


The procedure is the most common technique for code modularization. Tcl procedures: 


e¢ Can be invoked recursively. 

e Can be defined to accept specific arguments. 

e Can be defined to accept arguments that have default values. 
¢ Can be defined to accept a variable number of arguments. 


The proc command defines a Tcl procedure. 


Syntax: proc procName argList body 
Defines a new procedure. 
procName The name of the procedure to define. 
argList The list of arguments for this procedure. 
body The body to evaluate when this procedure is invoked. 


Note how the argument list and body are enclosed in curly braces in the following example. This is 
the normal way for defining a procedure, since you normally do not want any substitutions performed 
until the procedure body is evaluated. Procedures are discussed in depth in Chapter 7. 


=A 
Example 56 
Proc Example 
i## Define the classic recursive procedure to find the 
i## n’th position in a Fibonacci series. 
proc fib {num} { 
if {$num <= 2} {return l} 
return Lexpr [fib [expr $num -1]] + [fib [expr $num -2]] ] 
} 
for {set i l} {$i < 6} {incr i} { 
puts "Fibonacci series element $i is: [fib $i]" 


} 


Script Output 
fibonacci series element 1 is: 1 
fibonacci series element 2 is: 1 
fibonacci series element 3 is: 2 
fibonacci series element 4 is: 3 
fibonacci series element 5 is: 5 


).2 Loading Code from a Script File 


Splitting functionality into separate files, so that each file contains closely related procedures, makes 
code easier to maintain. The source command loads a file into an existing Tcl script. It is similar to 
the ##i nclude in C, the source in C-shell programming, and the require in Perl. This command lets 
you build source code modules you can load into your scripts when you need particular functionality. 
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This allows you to modularize your programs. This is the simplest of the Tcl commands that implement 
libraries and modularization. The package command is discussed in Chapter 8. 


Syntax: source fileName 
Load a file into the current Tcl application and evaluate it. 
fileName The file to load. 
Macintosh users have two options to the source command that are not available on other platforms. 


Syntax: source -rsrc resourceName ?fileName? 
Syntax: source -rsrcid resourceld ?fileName? 


These options allow one script to source another script from a TEXT resource. The resource may 
be specified by resourceName or resourcelID. 


Examining the State of the Tcl Interpreter 


Any Tcl script can query the Tcl interpreter about its current state. The interpreter can report whether 
a procedure or variable is defined, what a procedure body or argument list is, the current level in the 
procedure stack, and so on. The next examples will only use a few of the info subcommands. See the 
on-line documentation for details of the other subcommands. 


Syntax: info subCommand arguments 
Provide information about the interpreter state. 
subCommand Defines the interaction. Interactions include: 
exists varName Returns True if a variable has been 
defined. 
proc globPattern Returns a list of procedure names that 
match the g1ob pattern. 


body procName Returns the body of a procedure. 
args procName Returns the names of the arguments for a 
procedure. 


nameofexecutable Returns the full path name of the binary 
file from which the application was 
invoked. 


This example shows a procedure that counts the number of times values appear in a list and returns 
a list of values and the number of times they occur. It uses the info exists command to determine 
whether or not a value has been found (and counted) yet. 


—————— OOOO eee ee eee 
Example 57 
Using info Commands 


proc countListElements {lst} { 
i Step through each element in the list 
foreach 1 $lst { 
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if If the index exists, increment the count 
if {Linfo exists counts($1)]} { 
incr counts($1) 
} else { 
if If the index did not exist, initialize it 
set counts($1) 1 
} 
} 
return [array get counts] 


} 


if {Linfo proc countListElements] eq "countListElements"} { 
set testList {a b aac b a} 
puts "The countListElements procedure is defined." 
puts "The countListElements procedure returns" 
puts [LcountList $testList] 
puts "for the list {$testList}" 
} 


Script Output 


The countListElements procedure is defined. 
The countListElements procedure returns 
a4b2ecil1 

for the list {abaacb a} 


3.6 BOTTOM LINE 
This covers the basics of the Tcl language. The next chapter introduces the Tcl I/O calls, techniques for 
using these commands, and a few more commands. 


Tcl is a position-based language rather than a keyword-based language. 
A Tcl command consists of 
e Acommand name 
Optional subcommand, flags, or arguments 
e A command terminator [either a newline or semicolon (;)] 
Words and symbols must be separated by at least one whitespace (space, tab, or escaped newline) 
character. 
Multiple words or variables can be grouped into a single argument with braces ({}) or quotes (""). 
Substitution will be performed on strings grouped with quotes. 
Substitutions will not be performed on strings grouped with curly braces ({}). 
A Tcl command is evaluated in a single pass. 
The Tcl evaluation routine is called recursively to evaluate commands enclosed within square 
brackets. 
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Some Tcl commands can accept flags to modify their behavior. A flag will always start with a 
hyphen. It may proceed or follow the arguments (depending on the command) and may require an 
argument itself. 
Values are assigned to a variable with the set command. 
Syntax: set varName value 
Math operations are performed with the expr and incr commands. 
Syntax: expr mathExpression 
Syntax: incr varName ?incrValue? 
The branch commands are if and switch. 
Syntax: if {test} {bodyTrue} ?elseif {test2} {body2}? ?else {bodyFalse}? 
Syntax: switch ?option? string patternl bodyl\ 
?pattern2 body2? ?default defaultBody? 
The looping commands are for, while, and foreach. 
Syntax: for start test next body 
Syntax: while test body 
Syntax: foreach listVar list body 
The list operations include list, split, llength, lindex, and lappend. 


Syntax: list elementl ?element2? ... ?elementN? 
Syntax: linsert Jist position elementl ... ?elementN? 
Syntax: lappend JistName ?elementl? ... ?elementN? 


Syntax: split data ?splitChar? 
Syntax: join list ?joinString? 
Syntax: llength Jist 

Syntax: lindex list index 


Syntax: lsearch Jist pattern 


Syntax: lreplace Jist positionl position2 elementl ?... elementN? 
The string processing subcommands include first, last, length, match, toupper, 
tolower, and range. 

Syntax: string first substr string 

Syntax: string last substr string 

Syntax: string length string 

Syntax: string match pattern string 

Syntax: string toupper string 

Syntax: string tolower string 

Syntax: string range string first last 

Formatted strings can be generated with the format command. 

Syntax: format format ?data? ?data2? ... 


The scan command will perform simple string parsing. 

Syntax: scan textstring format ?varNamel? ?varName2? ... 

The array processing subcommands include array names, array set, andarray get. 
Syntax: array names arrayName ?pattern? 

Syntax: array set arrayName {indexl valuel ...} 

Syntax: array get arrayName 
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e Values can be converted between various ASCII and binary representations with binary scan 
and binary format. 
e The source command loads and evaluates a script. 
Syntax: source fileName 
e The info command returns information about the current state of the interpreter. 
Syntax: info proc 
Syntax: info args 
Syntax: info body 
Syntax: info exists 
Syntax: info nameofexecutable 


3.7 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under 
a minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page, or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material, or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e 100 What will the following code fragments display? 
e set al 

ts "$a" 

tal 

ts {$a} 

tal 

ts Lexpr $a + 1] 

t a b 

t $a 2 

ts "$b" 

ts ail! 

ts "\$$a" 


(a) 


Oo Oo (a) 


(a) 


On TN NDNA TD ND 


e 101 What are the Tcl’s three looping commands? 
e 102 What conditional commands does Tcl support? 


e 103 What command will define a Tcl procedure? 
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104 Can a Tcl procedure be invoked recursively? 

105 What is the first word in a Tcl command line? 

106 How are Tcl commands terminated? 

107 Can you use binary data in Tcl? 

108 How does a Tcl procedure return a failure status? 

109 What commands can modify the content of a variable? 

110 How could you change an integer to a floating-point value with the append command? 


111 Write a pattern for string match to match: 
e Strings starting with the letter A. 

e Strings starting with the letter A followed by a number. 

e Strings starting with a lowercase letter followed by a number. 
e Strings in which the second character is a number. 

e Three character strings of uppercase letters. 

e A question. 


112 What characters are returned by: 

e string range "testing" 0 0 

e string range "testing" 0 1 

e string range "testing" 0 99 

e string range "testing" O end 
e string range "testing" 99 end 
e string range "testing" end end 


113 Write a format definition that will: 

e Use 20 spaces to display a string, and left justify the string. 

e Use 20 spaces to display a string, and right justify the string. 

e Display a floating point number less than 100 with 2 digits to the right of the decimal point. 
e Display a floating point number in scientific notation. 

e Convert an integer to an ASCII character (i.e., convert 48 to 0”, 49 to ”1”, and so on). 


114 What is the second list element in the following lists? 
e {one two three four} 
e {one {two three} four} 
e  { {} one two three} 
{ {one two} {three four} } 


115 Which array command will return a list of the indices in an associative array? 


116 Which Tcl command could be used to assign a value to a single element in an associative 
array? 


117 Which Tcl command could be used to assign values to multiple elements in an associative 
array? 
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e 118 What binary scan format definition would read data that was written as this C structure?: 
struct { int i[4]; char c[25]; float f; } 


e /191If x and y are two Tcl variables containing the length of the opposite and adjacent sides of a 
triangle, write the expr command that would calculate the hypotenuse of this angle. 


e 120 Write a procedure that uses info commands to report all the procedures and arguments that 
exist in an interpreter. 


e 200 The classic recursive function is a Fibonacci series, in which each element is the sum of the 
two preceding elements, as in the following. 
1. P-2 38-8 213:-21 
Write a Tcl proc that will accept a single integer, and will generate that many elements of a 
Fibonacci series. 


e 201 Write a procedure that will accept a string of text, and will generate a histogram of how many 
times each unique word is used in that text. 


e 202 Write a procedure that will accept a set of comma-delimited lines, and will generate a 
formatted table from that data. 


e 203 Write a procedure that will check to see whether a string is a palindrome (if it reads the same 
backward and forward). Examples of palindromes include the words noon and radar, and the 
classic sentence Able was I ere I saw Elba. 


e 300 The bubble sort works by stepping through a list and comparing two adjacent members and 
swapping them if they are not in ascending order. The list is scanned repeatedly until there are no 
more elements in the wrong position. 

a. Write a recursive procedure to perform a bubble sort on a list of data. 
b. Write a loop-based procedure to perform a bubble sort on a list of data. 


e 301 Tcl has an |}sort command that will sort a list. Use the 1sort command to check the results 
of the bubble sort routines constructed in the previous exercise. 


e¢ 302 A trivial encryption technique is to group characters in sets of four, convert that to an integer, 
and print out the integers. Write a pair of Tcl procedures that will use the binary command to 
convert a plaintext message to a list of integers, and convert a list of integers into a readable string. 


CHAPTER 


Navigating the File System, 
Basic I/O and Sockets 


This chapter describes the Tcl tools for: 


e Navigating a file system 

e Finding files and their attributes 

e Reading and writing data to files or other applications 
e Using client- and server-side sockets 


NAVIGATING THE FILE SYSTEM 


Most modern operating systems represent file systems as some form of tree-structured system, with 
a single root node, and drives and directories descending from that single node. They represent the 
trees as a string of words defining the drives and subdirectories separated by some character. Most 
operating systems provide a library of system calls to interact with the file system. Unfortunately, many 
modern operating systems use different symbols for the directory separator, have different conventions 
for naming drives and subdirectories, and provide different library calls for interacting with the file 
system. 

The Tcl solution to multiple platforms is to provide a set of Tcl commands to generalize the interface 
between Tcl scripts and the underlying libraries. Interactions with the file system are handled by the 
cd, pwd, glob, and file commands. 

Your script can learn or change its current working directory with the pwd (Print Working Directory) 
and cd (Change Directory) commands. 

Syntax: pwd 

Returns the current working directory. 
Syntax: cd newDirectory 

Changes the default working directory. 


newDirectory Adirectory to make the current default 
directory for open, glob, and so on. 
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_———_—aA 
Example 1 
Script Example 

puts "Working Directory: [pwd]" 

cd /tmp 

puts "Working Directory: [pwd]" 


Script Output 
Working Directory: /home/clif 
Working Directory: /tmp 


The Tcl glob command allows a script to search a path for items with names or types that 
match a pattern. You can use glob to write scripts that will perform some action on each file in 
one or more directories without knowing in advance what files will be present. The g]10b command 
matches file names using the glob-style patterns described with the string match command in 
Section 3.3.3 

Syntax: glob ?-nocomplain? ?-types typeList? ?--? pattern 

-nocomplain Do not throw an error if no files match the pattern. 

-types typeList Return only the items that match the typeList. The 
typeList is a string of letters that describes the 
types of file system entities available. If the typeList 
includes these elements, they are combined with a 
logical OR operation. 
b A block-mode device 
c A character device 
d A directory 
f A normal file 
1 A symbolic link 
p A named pipe 
s A socket 
If the typeList includes these elements, they are 
combined with a logical AND operation. 
r A file with read access. 
w A file with write access. 
222? On MacOS 9 and earlier: A four-letter type is 
the type or creator of the file. For instance, TEXT for 
a TEXT-type file, or APPL for an Application-type 
file. OS X applications do not assign a value to type 
or creator. 

ea Identifies the end of options. All following arguments 

are patterns even if they start with a dash. 
pattern A glob-style pattern to match. 
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_.——_Ho-—-—_ 
Example 2 
Script Example 
foreach fileName [glob *.c *.h] { 
puts "C Source: $fileName" 


} 
Script Output 


C Source: tclUtil.c 

C Source: tclVar.c 

C Source: regcustom.h 
C Source: regerrs.h 


The - types option can be used to select only those types of file system entities you want to deal 
with. 


—— ehhh 
Example 3 
Script Example 


puts "The subdirectories under /usr are: [glob -types d /usr/x]" 


Script Output 
The subdirectories under /usr are: /usr/bin /usr/lib/usr/libexec 
/usr/sbin /usr/share /usr/X11R6 /usr/dict/usr/etc /usr/games 
/usr/include /usr/local /usr/sre /usr/kerberos/usr/i386-glibc21-linux 
/usr/man 


4.1.1 Constructing File Paths 


The pwd, cd, and glob commands provide an interface to the navigating of a file system that all 
operating systems support. The fi 1e commands provide an interface to services that may be platform 
specific. Like the string commands, the file commands are implemented as subcommands from 
the main fi 1e command. 

The file command includes many subcommands, including creating new directories, copying 
files, reading and modifying file information, creating links and creating new file names and paths. 

Tcl maintains file paths as Unix style paths inside a script, using a forward slash (/) to separate the 
subdirectories in a file path. The internal format path is automatically translated to native format when 
you pass a filename to an application with the exec command. 

For example, code like this works fine on a Windows system: 

exec notepad.exe "C:/My Documents/somefile.txt" 

Do not use the Windows-style backward slash within a Tcl script. The backward slash is used by 
Tcl to escape the character following it. You will end up confusing yourself with multiple layers of 
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backward slashes escaping more backward slashes. For example this command: 
set channel [open "C:/data/datafile" r] 
will work on Windows platforms, but this command: 
set channel [open "C:\data\datafile" r] 
will return an error that C: datadatafi1e cannot be opened. 
If you need the actual native file path (for instance, to write the path to a file), use the file 
nativename command. 


Syntax: file nativename path 
Return a native format path. 
path A path in Tcl format. 


——— ee OO 
Example 4 
Script Example 


puts [file nativename "C:/My Documents/letter.doc"] 


Script Output 


Windows: C:\My Documents\letter.doc 
Linux, Unix, Mac OS X: C:/My Documents/letter.doc 


You can use either relative or absolute paths within a Tcl script. If you need the absolute path, use the 
file normalize command to remove symbolic links, relative paths, and “/../” sequences from a file 
path. 
Syntax: file normalize path 
Returns an absolute path with no symlinks or relative portions 
path Acalculated path that may be relative, 
use symbolic links, etc. 


—————————EEEEE———————————_ SSS SSS SSS 
Example 5 

% Cd $env (HOME ) 

puts [file normalize "My Documents/myDoc.doc" ] 


Script Output 
Unix: /home/clif/My Documents/myDoc.doc 
Windows: C:/Documents and Settings/Clif/My Documents/myDoc.doc 
Mac OS X: /Users/clif/My Documents/myDoc.doc 
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You can construct file paths using the string, sp]it and 1 ist commands described in Chapter 2. It is 
usually easier to use the file splitand file join commands to split a full path into subdirectories 
or join a set of path elements into a full path. 


file split path 

Returns the path as a list split on the OS-specific or canonical directory markers. 

file join list 

Merges the members of list into a canonical file path with each list member separated by a 
forward slash. 


The file split command will convert either a native format file path or a Unix style file path to 
a Tcl list on any platform. It will only split a file path with backward slashes (a Windows style filepath) 
to a list on a Windows platform. 


The file join command will join a Tcl list into a file path using forward slashes. 
The fi 1e command includes more subcommands to simplify manipulating file paths. 


file dirname path 

Returns the portion of path before the last directory separator. 
file tail path 
Returns the portion of path after the last directory separator. 


file rootname path 


Returns the portion of path before the last extension marker. 


Example 6 

Script Example 
set path [file join “program files 
puts “join: $path" 
puts “dirname: [file dirname $path]" 
puts “root: [file rootname $path]" 
puts “tail: Cfile tail $path]" 
puts “normal: [file normalize $path]" 


Tcl bin wish.exe]" 


Script Output 
join: program files/Tcl/bin/wish.exe 
dirname: program files/Tcl/bin 
root: program files/Tcl/bin/wish 
tail: wish.exe 
normal: /Users/clif/program files/Tcl/bin/wish.exe 
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4.2 PROPERTIES OF FILE SYSTEM ITEMS 


Before a script attempts to open a file, it may need to know information about the file: its size, creation 
date, permissions, whether it has been backed up, and so on. The system library calls that report these 
data differ from platform to platform. The information can be accessed within a Tcl script using some 
of the fi 1e subcommands. 

The fi] e command supports the following subcommands that return information about files. 


Reporting a File’s Existence 
file exist path Returns true if a file exists, and false if it 
does not exist. 
Reporting a File’s Type 
file type path Returns the type of file referenced by path. 
The return value will be one of the following. 
file $path is the name of a normal file. 
directory $path is the name of a directory. 


characterSpecial $£pathis the name of a UNIX character 
I/O device (such as a tty). 


blockSpecial $path is the name of a UNIX block I/O 
device (such as a disk). 

fifo $path is the name of a UNIX fifo file. 

link $path is the name of a hard link. 

socket $path is the name of a named socket. 


For common tests, the f i 1e command includes the following subcommands. 
file isdirectory path Returns 1 if path is a directory; 0 if not. 
file isfile path Returns | if path is a regular file; 0 if not. 


Reporting Statistics about a File 

file stat path varName 

file lstat path varName Treats varName as an associative array and creates an 
index in that array for each value returned by the stat or 
lstat library call. If the underlying OS does not support a 
status field, the value will be —1. The new indices (and 
values) will be: 
atime Time of last access 


ctime Time of last change to directory information 


mtime Time of last modification of file content 
dev Device type 
gid Group ID of owner 
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ino Inode number for file 
mode — Protection mode bits 
nlink Number of hard links 
size Size in bytes 
type Type of file 
uid User ID number of owner 
file attributes path 
Return a list of platform-specific attributes of the item referenced by path. 
These values are returned as a name/value list. The values returned on a Unix system are group, 
owner, and permissions. The values returned on a Windows system are archive, hidden, 
longname, readonly, shortname, and system. The values returned on a Mac system are 
creator, readonly, hidden, andtype. 
file attributes path attributeName 
Return the value of a named platform-specific attribute of the item Referenced by path. 


file attributes path attributeName newValue 


Sets the value of the named attribute to newValue. 


file nativename path 


Returns pathName in the proper format for the current platform 


—_——— ee OO 
Example 7 


Script Example 
proc reportDirectory {dirName} { 
## file join merges the existing directory path with 
if the * symbol to match all items in that directory. 
foreach item [glob -nocomplain [file join $dirName *]] { 
if { [string match [file type $item] "directory"]} { 
reportDirectory $item 
} else { 
puts "$item is a [file type $item]" 
puts "Attributes are: [file attributes $item]" 
file stat $item tmpArray 
set name [file tail $item] 
puts "$name is: $tmpArray(size) bytes\n" 
} 


} 
} 


# Start reporting from the current directory 
reportDirectory { } 


98 CHAPTER 4 Navigating the File System, Basic I/O and Sockets 


Script Output 

# Unix output resembles: 

html/index.html is a file 

Attributes are: -group root -owner root -permissions 00644 

index.html is: 1945 bytes 

html/poweredby.png is a file 

Attributes are: -group root -owner root -permissions 00644 

poweredby.png is: 1154 bytes 

# Windows output resembles: 

C:/WINDOWS/Favorites/Personal Files.LNK is a file 

Attributes are: -archive 1 -hidden 0 
-longname {C:/WINDOWS/Favorites/Personal Files.LNK} 
-readonly 0 -shortname C:/WINDOWS/FAVORI~1/PERSON~1.LNK 
-system 0 

Personal Files.LNK is: 247 bytes 

Cc: /WINDOWS/Favorites/Graphics.LNK is a file 

Attributes are: -archive 1 -hidden 0 
-longname C:/WINDOWS/Favorites/Graphics.LNK 
-readonly 0 -shortname C:/WINDOWS/FAVORI~1/GRAPHICS.LNK 
-system 0 

Graphics.LNK is: 379 bytes 

# Mac Classic (OS 7, 8, 9) output resembles: 

:Build:Drag Drop Tclets is a file 

Attributes are: -creator WIsH -hidden 0 -readonly 0 -type APPL 

Drag Drop Tclets is: 257683 bytes 

:Build:Tclapplescript.shlb is a file 

Attributes are: -creator TclL -hidden 0 -readonly 0 -type shlb 

Tclapplescript.shlb is: 21056 bytes 

# Mac OS/X output resembles 

reportDirectory.tcl is a file 

Attributes are: -group _lpoperator -owner clif -permissions 00644 -readonly 0 
-creator {} -type {} -hidden 0 -rsrclength 0 

reportDirectory.tcl is: 410 bytes 


Note that names of the attributes in the file attributes command include the dash (-) character, 
and are returned as key/value pairs. Many Tcl extensions use this format to return collections of data. 
Data returned as key/value pairs can be easily accessed with the dict commands, or assigned to an 
array using the array set command. 


array set dataArray [file attributes $filePath] 
set owner [dict get [file attributes $filePath] -owner] 


REMOVING FILES 


The last thing a program needs to do with a file is remove it. The fi 1e command also provides access 
to the operating system function that will remove a file. 
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file delete pathName 
Deletes the file referenced by pathName. 


4.4 INPUT/OUTPUT IN TCL 


It is difficult to perform any serious computer programming without accepting data and delivering 
results. Tcl abstracts the input and output commands into two input commands and one output com- 
mand. Using these three commands, you can read or write to any file, pipe, device, or socket supported 
by tclsh or wish. A GUI-based wish script can perform user I/O through various graphics widgets 
but will use these three commands to access files, pipes to other programs, or sockets. 

All I/O in Tcl is done through channels. A channel is an I/O device abstraction similar to an I/O 
stream in C. The Tcl channel device abstraction is extended beyond the stream abstraction to include 
sockets and pipes. The Tcl channel provides a uniform abstract model of the UNIX, Mac OS, and MS 
Windows socket calls, so they can be treated as streams. 

The Tcl commands that open a channel return a handle that can be used to identify that channel. 
A channel handle can be passed to an I/O command to specify which channel should accept or provide 
data. These channels are predefined in Tcl, as follows. 


stdin Standard input: keyboard or a redirected file. 
stdout Standard output: usually the screen. 


stderr Error output: usually the screen. Note that Mac OS before OS/X and MS 
Windows do not distinguish between stdout and stderr. 


Output 


The puts command sends output to a channel. It requires a string to output as an argument. By default, 
this command will append a newline character to the string. 


Syntax: puts ?-nonewline? ?channel? outputString 
Send a string to a channel. 
?-nonewline? Do not append a newline character to the output. 


?channel? Send output to this channel. If this argument is not used, 
send to standard output. 


outputString The data to send. 


— $$$ 


Example 8 
% puts “Hello, "; puts "World " 
Hello, 
World 
% puts -nonewline “Hello, "; puts "World" 


Hello, World 
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The Tcl commands that input data are the gets and read commands. The gets command will read 
a single line of input from a channel and strip off any newline character. The gets command may 
return the data that was read or the number of characters that were read. The read command will read 
a requested number of characters, or until the end of data. The read command always returns the data 
that was read. 

The gets command is best for interactive I/O, since it will read a single line of data from a user. 
The read command is best used when there is a large body of text to read in a single read command, 
such as a file or socket, or when there is a need for single-character I/O. 


Syntax: gets channelID ?varName? 


Read a line of data from a channel up to the first newline character. The newline char- 
acter is discarded. 


channelID Read from this channel. 


?varName? If this variable name is present, gets will store the data in 
this variable, and will return the number of characters read. 
If this argument is not present, gets will return the line of 
data. 


AR]. AAA 
Example 9 
% gets stdin # A user types "Hello, World" at keyboard. 

Hello, World 

% gets stdin inputString # A user types "Hello, World" at keyboard. 

12 

% puts $inputString 

Hello, World P| 

A Tcl script can invoke the read command to read a specified number of characters, or to read data 
until an End-Of-File is encountered. If a script invokes the read command to read a specified number 
of characters and read encounters an End-Of-File before reading the requested number of characters, 
the read command will return the available characters and not generate an error. The read command 
returns the characters read. The read command may strip off the final newline character but by default 
leaves newlines intact. 


Syntax: read channelID numBytes 
Read a specified number of characters from a channel. 


channelID The channel from which to read data. 


numBytes The number of bytes to read. 


Syntax: read ?-nonewline? channelID 
Read data from a channel until an End-Of-File (EOF) condition. 
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?-nonewline? Discard the last character if it is a newline. 


channelID The channel from which to read data. 


$$$ 


Example 10 
if Read from stdin until an End-Of-File is encountered 
dt 


% read stdin # A user types Hello, World EOF 
Hello, World 

## Read 5 characters from stdin 

% read stdin 5 # A user types Hello, World 
Hello 


When the output channel is the standard output device, Tcl buffers text until it has a complete line 
(until a newline character appears). To print a prompt and allow a user to enter text on the same line, 
you must either reset the buffering with fconfigure or use the flush (see Section 4.5.2) command 
to force Tcl to generate output. 


—_——— ehhh 
Example 11 


Script Example 
puts -nonewline "What is your name? " 
flush stdout 
gets stdin name ;# User types name 
puts "Hello, $name. Shall we play a game?" 


Script Output 


What is your name? Dr. Falken 
Hello, Dr. Falken. Shall we play a game? 


.3 Creating a Channel 


A Tel script can create a channel with either the open or socket command. The open command can 
be used to open a channel to a file, a device, or a pipe to another program. The socket command can 
be used to open a client socket to a server or to open a server socket that will listen for clients. 


Syntax: open fileName ?access? ?permissions? 
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Open a file, device, or pipe as a channel and return a handle to be used to 
access this channel. 


fileName The name of the file or device to open. 


If the first character of the name is a pipe (|), the 
filename argument is a request to open a pipe 
connection to a command. The first word in the file 
name will be the command name, and subsequent 
words will be arguments to the command. 


?access? How this file will be accessed by the channel. The 
access option may be one of: 
r Open file for read-only access. 


r+ Open file for read and write access. File must 
already exist. 


W Open file for write-only access. Truncate file 
if it exists. 


w+ Open file for read and write access. Truncate 
the file if it exists, or create it if it does not 
exist. 


a Open file for write-only access. New data will 
be appended to the file. For versions of Tcl 
before 8.3, the file must already exist. With 
Tcl8.3, the behavior was changed to create a 
new file if it does not already exist. 


at Open file for read and write access. Create the 
file if it does not exist. Append data to an 
existing file. 


?permissions? If a new file is created, this parameter will be used to 
set the file permissions. The permissions argument 
will be an integer, with the same bit definitions as the 
argument to the creat system call on the operating 
system being used. 


= eee 
Example 12 
Script Example 

d## Open a file for writing - Note square brackets cause the Tcl command 

i## to be evaluated, and the channel handle returned by open 


## is assigned to the variable outputFile. 
set outputFile [open "testfile" "w"] 

i## send a line to the output file. 

puts $outputFile "This is line 1" 

puts $outputFile "This is line 2" 

puts $outputFile "This is line 3" 

## Close the file. 

close $outputFile 

i## Reopen the file for reading 

set inputFile Lopen "testfile" "r"] 

## Read a line of text 

set numBytes [gets $inputFile string] 

## Display the line read 

puts "Gets returned $numBytes characters in the string: 


i## Read the rest of the file 
set string2 [read $inputFi 


puts "Rea 


d: $st 


ring2" 


if Announce intent 


puts "\nOpening a Pipe\n" 


i## and open a pipe to t 


set pipe 


[open 


ices ea Oe 


## Equivalent command under 


i## set pipe [open "!com 


i## read the output of t 

while {!Leof $pipe]} { 
set length [gets $pi 
puts "$lsLine is $le 


} 


Script Output 


Gets returned 14 characters in the string: This is line 1 
Read: This is line 2 


This is 1 
Opening a 


ine 3 
Pipe 


and 


bin is 3 characters long 
boot is 4 characters long 
bsd is 3 characters long 


e 1s command 


pe lsLine] 


e] 


J 


MS-Windows is: 


.com fed ie "Ee ] 


e 1s command: 


gth characters long" 
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dev is 3 characters long 


4.4.4 Closing Channels 

The Tcl interpreter supports having multiple channels open simultaneously. The exact number is 
defined at compile time and by the underlying operating system. In order to process many files, your 
script will need to close channels after it has completed processing them. 


Syntax: close channel 
Close a channel. 


channel The handle for the channel to be closed. 


When a file that was opened for write access is closed, any data in the output buffer is written to the 
channel before it is closed. 


4.5 SOCKETS 


Most client/server applications such as Telnet, ftp, e-mail, web browsers, large database systems, chat 
programs, and so on use TCP/IP sockets to transfer data. The Tcl socket command creates a channel 
connected to a TCP/IP socket. The socket command returns a channel handle that can be used with 
gets, read, and puts just as a file channel is used. Unlike connections to files or pipes, there are 
two types of sockets. 


¢ Client socket (very much like a connection to a file or pipe) 
e Server socket (waits for a client to connect to it) 


Using the socket command to establish a client socket is as straightforward as opening a file. 
Syntax: socket ?options? host port 
Open a socket connection. 


?options? Options to specify the behavior of the socket. 
-myaddr addr Defines the address (as a name or 
number) of the client side of the socket. 
This is not necessary if the client machine 
has only one network interface. 


-myport port Defines the port number for the server 
side to open. If this is not supplied, the 
operating system will assign a port from 
the pool of available ports. 
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-async Causes the socket command to return 
immediately, whether the connection has 
been completed or not. 


host The host to open a connection to. May be a name or a 
numeric IP address. 


port The name or number of the port to open a connection 
to on the host machine. 


4.5.1 Using a Client Socket 
The outline of a Tcl TCP/IP client looks as follows. 


set server SERVERADDRESS 
set port PORTNUMBER 


set connection [socket $server $port] 


puts $connection "COMMAND" 
flush $connection 
gets $connection result 


analysisProcedure $result 


The next example demonstrates how to open a socket to a remote Post Office Protocol (POP) server 
to check for mail and shows how Tcl I/O and string commands can be used to develop an Internet client. 
The POP 3 message protocol is an ASCII conversation between the POP 3 client (your machine) and 
the POP 3 server (the remote machine). If you used POP from a Telnet client to learn if you have mail 
waiting, the conversation would resemble the following. 


$> telnet pop.example.com pop3 

Trying 123.456.789.012 

Connected to 123.456.789.012 

Escape character is ’4]’. 

+0K QPOP (version 2.2-krb-IV) at pop.example.com starting. 
<28004.887684070@pop.example.com> 

user ImaPopper 

+0K Password required for ImaPopper. 

pass myPassword 

+0K ImaPopper has 1 message (1668 octets). 


The following example will contact a remote machine and report if any mail is waiting. The 
machine name, user name, and password are all hard-coded in this example. The test for +OK is done 
differently in each test to demonstrate some different methods of checking for one string in another. 
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———_  O38OF> aaa 
Example 13 


Script Example 


i## Open a socket to a POP server. Report if mail is available 
i## Assign a host, login and password for this session 
set popHost example.com 


set popLoginID myID 
set popPasswd SecretPassword 


i## Open the socket to port 110 (POP3 server) 
set popClient [socket $popHost 110] 


## Get the first line: 
## +0K QPOP (version ..) at example.com starting... 


set line [gets $popClient] 


i## We can check for the ‘OK’ reply by confirming that ‘OK’ 
i## is the first item in the string 
if {[string first "+0K" $line] != O} { 

puts "ERROR: Did not get expected ‘+0K’ prompt" 

puts "Received: $line" 

exit; 


} 


it send the user name 
i## Note that the socket can be used for both input and output 


puts $popClient "user $popLoginID" 


i## The socket is buffered by default. Thus we need to 
if either fconfigure the socket to be non-buffered, or 
i## force the buffer to be sent with a flush command. 


flush $popClient 
if Receive the password prompt: 


if +0K Password required for myID. 


set response [gets $popClient] 
if We can also check for the ‘OK’ using string match 
if {{string match "+0K*x" $response] == O} { 

puts "ERROR: Did not get expected ‘+0K’ prompt" 

puts "Received: $response" 

exit; 
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} 


if Send Password 


puts $popClient "pass $popPasswd" 
flush $popClient 


jf Receive the message count: 
df +OK myID has 0 messages (0 octets). 


set message [gets $popClient] 


if {!£string match "+0K*x" $message]} { 
puts "ERROR: Did not get expected ‘+0K’ prompt" 
puts “Received: $message" 
exit; 


} 


puts [string range $message 3 end] 


Script Output 


myID has 2 messages (2069 octets). 
| 


You can put together a client/server application with just a few lines of Tcl. Note that the error 
messages use an apostrophe to quote the +OK string. In Tcl, unlike C or shell scripts, the apostrophe 
has no special meaning. 


4.5.2 Controlling Data Flow 


When a script tries to read past the end of a file, Tcl will return —1 as the number of characters read. 
A script can test for an End-Of-File condition with the eof command. 


eof channelID 


Returns true if the channel has encountered an End-Of-File condition. 


By default, Tcl I/O is buffered, like the stream-based I/O in the C standard library calls. This is 
usually the desired behavior. If this is not what your project needs, you can modify the behavior of the 
channel or flush the buffer on demand. 

The fconfigure command lets you define the behavior of a channel. You can modify several 
options, including whether to buffer data for this channel and the size of the buffer to use. The fcon- 
figure command allows you to configure more options than are discussed in this book. Read the 
on-line documentation for more details. 


Syntax: fconfigure channelID ?name? ?value? 
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Configure the behavior of a channel. 
channelID The channel to modify. 


name The name of a configuration field, which includes the 
following. 


-blocking boolean 


If set true (the default mode), a Tcl program will block 
ona gets or read until data is available. 


If set false, gets, read, puts, flush, and 
close commands will not block. 


-buffering newValue 


If newValue is set to ful 1, the channel will use 
buffered I/O. 


If set to | ine, the buffer will be flushed whenever a full 
line is received. 


If set to none, the channel will flush whenever 
characters are received. 


By default, files and sockets are opened with 
full buffering, whereas stdin and stdout are 
opened with 1 ine buffering. 


The fconfigure command was added to Tcl in version 7.5. If you are writing code for an earlier 
revision of Tcl, or if you want to control when the buffers are flushed, you can use the f 1] ush command. 
The f1ush command writes the buffered data immediately. 


Syntax: flush channelID 
Flush the output buffer of a buffered channel. 


channelID The channel to flush. 


The previous POP client example could be written without the flush $popC1lient commands if 
the following lines had been added after the socket command. 


i## Turn off buffering 
fconfigure $popClient -buffering none 


You can write simple applications using the traditional top-to-bottom flow of initiating a read and 
blocking until the data is available. If necessary, you could implement a round-robin loop by using the 
f configure command to set a channel to be non-blocking. More complex applications (perhaps with 
multiple open channels) require some sort of event-driven programming style. The Tcl fileevent 
command allows you to implement event-driven I/O in a script. The fi ]eevent command registers 


4.5 Sockets 109 


a script to be evaluated when a channel either has data to read or is ready to accept data in its write 
buffer. Registering a callback script is a common paradigm for event-driven programming in Tcl. 


Syntax: fileevent channel direction script 


channel The channel to watch for file events on. 


direction The direction of data flow to watch. May be readable or 
writable. 


script A script to invoke when the condition becomes true. 
(A channel has data or can be written to.) 


We can write a simple syslog daemon, as shown in the next example. Pay attention to the use 
of quotes and backslashes in the fileevent script. The quotes are used because the $1 0gFile and 
$socket substitution must be done before the script is registered. The square brackets are escaped 
because that substitution must be done when the script is evaluated. The script that is registered with 
the fi leevent will look something like the following. 


puts file2 [gets sockl23]. 


If the script were enclosed in curly braces, instead of quotes, no substitution would occur, and the 
script to be evaluated would be "puts $logFile \Lgets $socket\]". When data becomes avail- 
able on the channel, this script would be evaluated, and would throw an error, since the 1 ogF ile vari- 
able is a local variable that was destroyed when the createLogger procedure stopped being active. 


——————— eee eee ee eee 
Example 14 


proc createLogger {socket} { 
i# Open a file for data to be logged to 
set logFile [open C:\event.log w] 


if When the socket is written to, read the data 
# and write it to the log file. 
fileevent $socket readable "puts $logFile \[gets $socket\]" 


4.5.3 Server Sockets 


Creating a TCP/IP server is a little different from a client-side socket. Instead of requesting a con- 
nection, and waiting for it to be established, the server-side socket command registers a script to be 
evaluated when a client socket requests a connection to the server. 


Syntax: socket -server script port 
script A script to evaluate when a connection is established. 


This script will have three arguments appended to the script 
before it is evaluated. 
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channel The I/O channel that is assigned to this session. 
IP The address of the client requesting a connec- 
Address tion. (You can use this for simple Access List 


security tests.) 


port The port being used by the client-side socket. 


port The port to accept connections on. 


The outline for a Tcl TCP/IP server follows. Note the test for the End-Of-File in the readLine 
procedure and the vwait command at the end of the script. When the other end of a socket is closed it 
can generate spurious readable events that must be caught in the file event-handling code. If not, the 
server will receive continuous readable events, the gets command will return an empty string (and 
—1 characters), and the system will be very busy doing nothing. This test (or something similar) will 
catch that condition and close the channel, which will unregister the fi ]leevent. 

The normal tclsh script is read and evaluated from top to bottom, and then the program exits. 
This behavior is fine for a filter-type program, but not good for a server. A server program must sit 
in an event loop and wait for connections, process data, and so on. The vwait command causes 
the interpreter to wait until a variable is assigned a new value. While it is waiting, it processes 
events. 


Syntax: vwait varName 


varName The variable name to watch. The script following the vwait 
command will be evaluated after the variable’s value is 
modified. 


proc serverOpen {channel addr port} { 
i## Set up fileevent to be called when input is available 


fileevent $channel readable "“readLine $channel" 


} 


proc readLine {channel} { 
set len [gets $channel line] 


if If we read O or -1 characters, check for EOF. 
i If EOF, close the channel and delete that client entry. 


if {($len <= 0)&&Leof $channel J} { 
close $channel 
} else { 
if Process Line of Data 
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set serverPort PORTNUMBER 
set server [socket -server serverOpen $serverPort] 


i Initialize a variable and wait for it to change 
if to keep tclsh from exiting. 
set running 1 
vwait running 
The next example shows a simple server that will watch a file, and send a notice whenever the file 
is changed. This type of script might be used on a firewall to report if the registry, or files in /bin 
or C:/winnt, are modified. In this case, the script is watching the UNIX password file. If this file 
changes size, it means a new user has been added to the system. 
The after command will register a script to be evaluated after a time interval. This is discussed in 
more detail in Chapter 9. 


=.—_—aA—_A_A 
Example 15 
proc serverOpen {channel addr port} { 

# Set up fileevent to be called when input is available 

initializeData /etc/passwd 
after 2000 "examineFiles $channel /etc/passwd" 
} 
proc initializeData {filename} { 
global fileData} 
file stat $filename fileData 


} 
proc examineFiles {channel filename} { 
global fileData 
file stat $filename newData 
foreach index Larray names newData] { 
if {$newData($index) != $fileData($index) }{ 
puts $channel "$filename: $index has changed" 
puts $channel " was: $fileData($index) now: $newData($index)" 
flush $channel 


} 
} 
file stat $filename fileData 
after 2000 "examineFiles $channel $filename" 
} 
set serverPort 12345 
set server [socket -server serverOpen $serverPort ] 
set done 0 
vwait done 


112 


To test this program, you might telnet to the server in one window, and modify the test file in another 
to see if you get a report. The IP address 127.0.0.1 is always your current host computer. This is 
called the loopback address. This example watches the /etc/passwd file, and will report whenever 
the file is modified. When someone attempts to log into the system, or a program checks that a user 
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name is valid, the access time (- at ime) attribute will change. 


C:> telnet 127.0.0.1 12345 

Trying 127.0.0.1... 

Connected to localhost (127.0.0.1). 
Escape character is ‘4]’. 
/etc/passwd: atime has changed 


was: 


1023112769 now: 1023112872 


/etc/passwd: atime has changed 


was: 


1023112872 now: 1023112888 


4.6 BOTTOM LINE 

e The pwd command will return the current working directory. 

e The cd newDir command will change the current working directory. 

e The glob command will return file system items that match a pattern or type. 

e Multiplatform file system interactions are supported with the following fi 1e commands. 


file exist path 


Returns true if a file exists, and false if it does not exist. 


file type path 
Returns the type of file referenced by path. The return value will be 
file, directory, characterSpecial, blockSpecial, fifo, link, or 
socket. 


file attributes path 


Returns a list of platform-specific attributes of the item referenced by path. 


file stat path varName 
Treats varName as an associative array and creates an index in that array for each 
value returned by the stat library call. 

file split path 
Returns the path as a list, split on the OS-specific directory markers. 

file join list 
Merges the members of list into an OS-specific file path, with each list member 
separated by the OS-specific directory markers. 
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file dirname path 


Returns the portion of path before the last directory separator. 


file tail path 


Returns the portion of path after the last directory separator. 


file rootname path 


Returns the portion of path before the last extension marker. 


file attributes path attributeName 


Returns the value of a named platform-specific attribute of the item referenced 
by path. 


file attributes path attributeName newValue 
Sets the value of the named attribute to newValue. 


e The open command will open a channel to a file or pipe. 

e The socket command will open a client or server-side socket. 

e The puts command will send a string of data to a channel. 

e The gets command will input a line of data from a channel. 

e The read command will input one or more bytes of data from a channel. 

e The fconfigure command will modify the behavior of a channel. 

e The fileevent command will register a script to be evaluated when a channel has data to read, or 
can be written to. 

e The eof command returns true if the End-Of-File has been reached or a socket has been closed. 

e The close command will close a channel. 


4.7 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under 
a minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 
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e 100 Can a Tcl script change the current working directory? 


e 101 Cana Tcl open command be given a relative path to the file to open, or must it be an absolute 
path? 


e 102 What Tcl command will return a list of all the files in a directory? 
e 103 What features of a file are reported by the file attributes command? 


e 104 Why should you use file join instead of assembling a file path using the string 
commands? 


e 105 Can Tcl be used for event-driven programming? 
e 106 Cana TCP/IP server written in Tcl have more than one client connected at a time? 


e 107 What Tcl command or commands would convert /usr/src/tcl8.4.1/generic/tcl.h to 
the following? 


e tcl.h 

e /usr/src/tcl8.4.1/generic/tcl 
e tcl 

e /usr/src/tcl8.4.1/generic 

® generic 


e 108 Can a single Tcl puts command send data to more than one channel? 
e 109 What Tcl command can be used to input a single byte of data from a channel? 


e 110 Given an executable named reverse that will read a line of input from stdin and output 
that line of text with the letters reversed, what commands would be used to open a pipe to the 
reverse executable, send a line of text to the reverse process, and read back the reply? 


e 111 Which two commands will cause an output buffer to be flushed? 


e 112 Tf you wish your application to flush the output buffer whenever a newline is received, what 
Tcl command would you include in the script? 


e 200 Example 4.2.3-1 watches a single file. Modify this example so that the initializeData and 
examineFiles procedures can accept a list of files to watch. 


e 20] Write a Tcl script that will read lines of text from a file and report the number of words in the 
file. 


e 202 Write a script that will list the object files in a directory that are older than the appropriate 
source file. 


e 203 Write a script that will list files in a directory in size order. 


e 204 Write a script that will report the oldest file in a set of directories by recursively searching 
subdirectories under a parent directory. 


e 205 Write a script that will recursively search directories for files that contain a particular pattern. 


4.7 Problems 115 


206 Write a TCP/IP server that will accept a line of text, and will return that line with the words in 
reverse order. 


300 Write a TCP/IP client that will: 
e Prompt a user for a port 
e Open a client socket to IP Address 127.0.0.1 and the port provided by the user 
e Ina loop: 
i. Prompt the user for input 

ii. Send the text to a server 

iii. Accept a line of data from the server 

iv. Display the response to the user 
Do not forget to append a newline character to the user input and f 1ush the output socket. 


301 Write a TCP/IP server that will send three questions (one at a time) to a client, accept the 
input, and finally generate a summary report. The conversation might resemble the following. 


Server: What is your name? 
Client: Lancelot 
Server: What is your quest? 
Client: To find the holy grail 
Server: What is your favorite color? 
Client: Blue 
Server: Your name is Lancelot. 
You like Blue clothes. 
You wish To find the holy grail. 


Test this server by connecting to it with a Telnet client, or using the test client described in the 
previous example. 


302 Write a TCP/IP server that will accept a line of numbers and will return the sum of these 
values. Write a client that will exercise and test this server. The client-server conversation might 
resemble the following. 


Client: 123987 
Server: 30 


303 Modify the previous server so that it will return the wrong answer if the correct sum is 30. 
Confirm that your client will catch this error. 


CHAPTER 


Using Strings and Lists 


This chapter describes how to use Tcl strings and lists for common data-searching applications. A 
common programming task is extracting one piece of information from a large mass of data. This 
section discusses several methods for doing that and introduces a few more Tcl concepts and commands 
along the way. 

For the application, we will find the Noumena Corporation home page in a list of uniform resource 
locators (URLs) for some Tcl information and archive sites. The following is the starting data, extracted 
and modified from a browser’s bookmark file. 


% set urls { 

wiki.tcl.tk "Tcler’s Wiki" 

core.tcl.tk "Tcl/Tk Fossil Core" 
sourceforge.net/projects/tcl/ "Sourceforge Tcl" 
sourceforge.net/projects/tktoolkit/ "Sourceforge Tk" 
www.noucorp.com "Noumena Corporation" 
www.activestate.com "ActiveState" 

www.tcl.tk/ "Tcl Developer’s Exchange" 
expect.nist.gov/ “Expect Home Page" 
www.tclcommunityassociation.org "Tcl/Tk Community Association 
} 


CONVERTING A STRING INTO A LIST 


Since the data has multiple lines, one solution is to convert the lines into a list and then iterate through 
the list to check each line. 


$$ $$$ 
Example 1 
Splitting Data into a List 

# Split data into a list at the newline markers 

set urlList [split $urls "\n"] 

dt display the list 

puts $urlList 


Tel/Tk: A Developer’s Guide. DOI: 10.1016/B978-0-12-384717-1.00005-1 1 1 7 
© 2012 Elsevier, Inc. All rights reserved. 


118 CHAPTER 5 Using Strings and Lists 


Script Output 
{} {wiki.tcl.tk "Tcler’s Wiki"} 
{core.tcl.tk "Tcl/Tk Fossil Core"} 
{sourceforge.net/projects/tcl/ "Tcl at Sourceforge"} 
{sourceforge.net/projects/tktoolkit/ "Tk at Sourceforge"} 
{www.noucorp.com "Noumena Corporation"} 
{www.activestate.com "ActiveState"} 
{www.tcl.tk/ "Tcl Developer’s Exchange"} 
{expect.nist.gov/ "Expect Home Page"} 
{www.tclcommunityassociation.org "Tcl/Tk Community Association"} 
{} 
| 


Note that the empty lines after the left bracket and before the right bracket were converted to empty 
list entries. This is an artifact of the way the starting data was defined. If it had been defined as: 


% set urls {wiki.tcl.tk "Tcler’s Wiki" 

core.tcl.tk "Tcl/Tk Fossil Core" 

sourceforge.net/projects/tcl/ "Sourceforge Tcl" 
sourceforge.net/projects/tktoolkit/ "Sourceforge Tk" 
www.noucorp.com "Noumena Corporation" 

www.activestate.com "ActiveState" 

www.tcl.tk/ "Tcl Developer’s Exchange" 

expect.nist.gov/ "Expect Home Page" 
www.tclcommunityassociation.org "Tcl/Tk Community Association" } 


the empty list elements would not be created, but the example would be a bit less readable. This 
example code will not be bothered by the empty lists, but you may need to check for that condition in 
other code you write. The sp1it command will convert text to a list at every occurrence of the split 
characters, whether you expect it to convert at that location or not. 


5.2 EXAMINING THE LIST WITH A for LOOP 


Now that the data is a list, we can iterate through it using the numeric for loop introduced in Chapter 3. 
The section following the example explains in detail what happens when this script is evaluated. 


Syntax: for start test next body 


———————————— eee eee 
Example 2 


Search Using a for Loop 


for {set pos 0} {$pos < [llength $urlList]} {incr pos} { 
set testLine [Llindex $urlList $pos] 
if {[string first "Noumena" $testLine] >= 0} { 
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puts "NOUMENA PAGE:\n $testLine" 
} 
} 


Script Output 
NOUMENA PAGE: 


www.noucorp.com "Noumena Corporation" 


for {set pos 0} {$pos < [llength $urlList]} tincr pos} { 


This line calls the for command. The for command takes four arguments: start, test, next, 
and a body to evaluate. Notice that this line shows only three arguments (start, test, and next) 
but no body. There is only a left curly brace for the body of this command. 

The curly braces cause all characters between the braces to be treated as normal text with no special 
processing by the Tcl interpreter. Variable names preceded by dollar signs are not replaced with their 
value, the code within square brackets will not get evaluated, and the newline character is not inter- 
preted as the end of a command. So, placing the curly braces at the end of the for line tells the Tcl 
interpreter to continue reading until it reaches the matching close bracket, and treat that entire mass of 
code as the body for this for command. The following code would generate an error. 


% for {set i 1} {$i < 10} tincr 7} 
{ 
set x Lexpr $x + $i] 
} 


A Tcl interpreter reading the line for {set i 1} {$i < 10} {incr i} would find a for com- 
mand (and start, test, and next arguments) and would then see the End-Of-Line and nothing to 
tell the interpreter that the next line might be part of this command. The interpreter would return the 
following error to inform the programmer that the command could not be parsed correctly. 


% wrong # args: should be "for start test next command" 


The Tcl Style Guide created by the Tcl development group at Sun Microsystems recommends that 
you place the body of an if, for, proc, or while command on a separate line from the rest of the 
command, with just the left bracket on the line with the command to inform the compiler that the body 
of the command is continued on the following lines. The following code is correct. 


for {set i 0} {$i < 100} {incr i} { 
puts "I will write my code to conform to the standard" 
} 


Note that the arguments to the for command in both sets of example code are grouped with curly 
braces, not quotes. If the arguments were grouped with quotes, a substitution pass would be performed 
on the arguments before passing them to the for command. The variable pos has not been defined, so 
attempting a substitution would result in an error. If pos had already been defined as 10 (perhaps in a 
previous for loop), variable substitutions would be performed and the first line would be passed to the 
for command, as in the following. 


for {set pos 0} "10 < 10" {incr pos} { 
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With the variables in the test already substituted, the test will always either fail or succeed 
(depending on the value of the variable), and the loop will not do what you expect. For the same 
reason, the body of a for command should be grouped with braces instead of quotes. You do not 
want any variables to be substituted until the loop body is evaluated. Given that no substitution hap- 
pens to the variables enclosed in curly braces, you may be wondering how the code in one scope 
(within the for command) can access the variables in another scope (the code that invoked the for 
command). 

The Tcl interpreter allows commands to declare which scope they should be evaluated in. This 
means that commands such as for, if, and while can be implemented as procedures and the body 
of the command can be evaluated in the scope of the code that called the procedure. This gives these 
commands access to the variables that were enclosed in curly braces and allows the substitution to be 
done as the command is being evaluated, instead of before the evaluation. 

For internal commands such as for, if, and while, the change of scope is done within the Tcl 
interpreter. Tcl script procedures can also use this facility with the uplevel and upvar commands, 
which are described in Chapter 7. There are examples using the uplevel and upvar commands in 
Chapters 7-12, 16, and 19. 

The start and next arguments to the for command are also evaluated in the scope of the calling 
command. Thus, pos will have the last value that was assigned by the next phrase when the for loop 
is complete and the line of code after the body is evaluated. 


set testLine [Llindex $urlList $pos] 


This extracts the list element at position $pos and assigns it to the variable testLine. The value 
of the variable pos is incremented on each pass through the loop, thus the value of testLine steps 
through the list on each pass through the loop. 

This line could have been omitted, and the 1index command could be used to extract the list 
element each time it was needed. If a value is going to be created and used multiple times, it’s usually 
better code style to assign it to a variable, rather than duplicating the code that creates the value. 


if {{string first "Noumena" $testLine] >= 0} { 


Like the for command, the i f command accepts an expression and a body of code. If the expres- 
sion is true, the body of code will be evaluated. As with the for command, the test expression goes on 
the same line as the i f command, but only the left brace of the body is placed on that line. The test for 
the if is grouped with brackets, just as is done for the for command. 

Within the test expression, there is a nested Tcl command. This will be evaluated before the 
expression is evaluated. The command [string first "Noumena” $testLine] will be replaced 
by either the position of the string Noumena in the target string or —1 if Noumena is not in the list 
element being examined. 


puts "NOUMENA PAGE:\n $testLine" 


If the test evaluates to true, the puts command will be evaluated; otherwise, the loop will con- 
tinue until $pos is no longer less than the number of entries in the list. The argument to puts is in 
quotes rather than curly braces to allow Tcl to perform substitutions on the string. This allows Tcl to 
replace the \n with a newline and $testLine with the list element at $pos. 


5.4 Using string match Instead of string first 121 


5.3 USING THE foreach COMMAND 


Using a for command to iterate through a list is familiar to people who have coded in C or FORTRAN, 
which are number-oriented languages. Tcl is a string- and list-oriented language. Tcl has better ways to 
iterate through a list. For instance, we could use the foreach command instead of the for command 
to loop through the list. 


Syntax: foreach varname list body 


eee 
Example 3 


Search Using a foreach Loop 


foreach item $urlList { 
if {Lstring first "Noumena" $item] >= 0} { 
puts "NOUMENA PAGE:\n $item" 
} 
} 


Script Output 


NOUMENA PAGE: 
www.noucorp.com "Noumena Corporation" 


Using the foreach command the code is somewhat simpler, because the foreach command 
returns each list element instead of requiring the 1 index commands to extract the list elements. 


5.4 USING string match INSTEAD OF string first 


There are other options that can be used for the test in the if statement. 


——— reson 
Example 4 


Search Using a string match Test 


% foreach item $urlList { 
if {Lstring match {*[Nn]oumenax} $item]} { 
puts "NOUMENA PAGE:\n $item" 
} 
} 


Script Output 
NOUMENA PAGE: 
www.noucorp.com "Noumena Corporation" 
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The string match command will compare a glob style pattern to a string and return true if the 
pattern matches the string. The glob pattern rules are described in Section 3.3. 

Note that the pattern argument to the string match command is enclosed in braces to prevent 
Tcl from performing command substitutions on it. The pattern includes the asterisks because string 
match will try to match a complete string, not a substring. The asterisk will match to any set of 
characters. The pattern {*[Nn]oumenax} causes string match to accept as a match a string that has 
the string noumena or Noumena with any sets of characters before or after. 


USING lsearch 


We could also extract the Noumena site from the list of URLs using the 1search command. The 
]1search command will search a list for an element that matches a pattern. 


Syntax: lsearch ?mode? list pattern 
Return the index of the first list element that matches pattern or —1 if no element 
matches the pattern. 
?mode? The type of match to use in this search. 


?mode? may be one of: 


-exact The list element must exactly match the pattern. 
-glob The list element must match pattern using 
the g1] ob rules. 
-regexp The list element must match pattern using the 
regular expression rules. 
list The list to search. 


pattern The pattern to search for. 


BB  —0€0€C SS SS SIs«>aaax. 
Example 5 


Search Using an |search 


set index [lsearch —glob $urlList "*xNoumenax" ] 
if {$index >= 0} { 

puts "NOUMENA PAGE:\n[lindex $urlList $index]" 
} 


Script Output 
NOUMENA PAGE: 
www.noucorp.com "Noumena Corporation" 


Note that this solution will only find the first list element that matches *Noumenax. 
For versions of Tcl before 8.5, to find multiple matches, you will need a loop as follows. 
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ee eer 
Example 6 


Script Example 


set 1 {phaser tricorder {photon torpedo} \ 
transporter communicator} 
i## Report all list elements with an ‘a’ in them. 
while {Lset p Llsearch $1 "xax"]] >= 0} { 
puts "There’s an ‘a’ in: [Llindex $1 $p]" 
incr p 
set 1 Llrange $1 $p end] 
} 


Script Output 
There’s an ‘a’ in: phaser 
There’s an ‘a’ in: transporter 
There’s an ‘a’ in: communicator 


Tcl version 8.5 added new options to the 1search command to make finding multiple matches 
easier: 

-start num Return the first list element that matches the pattern after this location. 

-all Return a list of all the list elements that match the pattern. 


-inline Return the list element instead of position. 
Using the -start option removes the need to reduce the size of the list on each pass through the 
whi le loop. 


ooo nnn Oem» 
Example 7 


Script Example 


set 1 {phaser tricorder {photon torpedo} \ 
transporter communicator} 

## Report all list elements with an ‘a’ in them. 

set first 0 

while {[set p Llsearch —start $first $1 "xax"]] >= 0} { 
puts "There’s an ’a’ in: [Llindex $1 $p]" 
set first Lincr p] 

} 


Script Output 
There’s an ‘a’ in: phaser 
There’s an ‘a’ in: transporter 
There’s an ‘a’ in: communicator 
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The -start option will find the next list element that matches a pattern at or after the defined 
location. That’s why the value of first is incremented to be one location past the location of the 
previous match. 

The solution gets even simpler if you use the -a11 option to get a list of all the indices that match 
the pattern using just one call to the 1search command. 


set 1 {phaser tricorder {photon torpedo} \ 
transporter communicator} 
i## Report all list elements with an ‘a’ in them. 
foreach pos [lsearch -all $1 "“xa*"]} { 
puts "There’s an ‘a’ in: [Llindex $1 $pos]" 
} 


The final simplification is to use the - in] ine option to get the actual list element, instead of using 
the 1 index command to extract the list element. 


set 1 {phaser tricorder {photon torpedo} \ 
transporter communicator} 
## Report all list elements with an ‘a’ in them. 
foreach val [lsearch -inline -all $1 "*ax"]} { 
puts "There’s an ‘a’ in: $val" 
} 


5.6 THE regexp COMMAND 


The regular expression commands in Tcl provide finer control of string matching than the g1 0b method, 
more options, and much more power. 


5.6.1 Regular Expression Matching Rules 

A regular expression is a collection of short rules that can be used to describe a string. Each short rule 
is called a piece, and consists of an element that can match a single character (called an atom) and an 
optional count modifier that defines how many times this atom may be matched in the string. If the 
count modifier is omitted, the atom will be matched once. 


Basic Regular Expression Rules 
This table shows the ways an atom can be defined. 


Definition Example Description 

A single character x will match the character x . 

A range of characters [a-q] will match any lowercase letter between a and q 
enclosed in brackets (inclusive). 

A period : will match any character. 

A caret is matches the beginning of a string. 


(Continued) 
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Definition Example 
A dollar sign $ 

A backslash sequence Ne 

A regular expression enclosed ({Tt]lcl) 
in parentheses 


Description 


matches the end of a string. 


inhibits treating *, , $, +, *%, andsoonas 
special characters, and matches the exact 
character. 


will match that regular expression. 


A regular expression could be as simple as a string. Forexample, this is a regular expres- 
sion is a regular expression consisting of 28 atoms, with no count modifiers. It will match a string that 
is exactly the same as itself. The range atom ([a-z]) needs a little more explanation, since there are 
actually several rules to define a range of characters. A range consists of square brackets enclosing the 


following. 
Definition Example Description 
A set of characters [tel Any of the letters within the brackets may match 
the target. 
Two characters separated by [a-z] The letters define a range of characters that may 
a dash match the target. 
A character preceded by a iaaeael Any character except the character after the 
caret, if the caret is the first caret may match the target. 
letter in the range 
Two characters separated by az Any character except characters between the 
a dash and preceded by a two characters after the caret may match the 
caret, if the caret is the first target. 
letter in the range 


The regular expression [Tt ][Cc][L1] would match a string consisting of the letters T, C, and L, 
in that order, with any capitalization. The regular expression [TtCcL1 ]* would match those letters in 


any order. 


A count modifier may follow an atom. If a count modifier is present, it defines how many times the 
preceding atom can occur in the regular expression. The count modifier may be the following. 


Definition Example 
An asterisk ax 

A plus at 

A question mark [a-z]? 


Description 


Match 0 or more occurrences of the preceding 
atom (a). 

Match 1 or more occurrences of the preceding 
atom. 


Match 0 or 1 occurrence of the preceding atom. 


(Continued) 
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Definition Example Description 
A bound {3} An integer that defines exactly the number of 
matches to accept. 

{3,} The comma signifies to match at least three 
occurrences of the previous atom, and perhaps 
more. 

{3,5} A pair of numbers representing a minimum and 
maximum number of matches to accept. 


Support for count modifier bounds was added in Tcl 8.1. Versions of Tcl earlier than that only 
support the asterisk, plus, and question mark count modifiers. 


5.6.2 Examples of Regular Expressions 


As a very simple example, the regular expression Ax would match a string of a single letter A, a string 
of several letter As, or a string with no A at all. 

The regular expression [A-Z]+[0-9A-Z]* is more useful. This regular expression describes a 
string that starts with at least one uppercase alphabetic character, followed by 0 or more alphanumeric 
characters. This regular expression describes a legal variable name in many programming languages. 

Regular expression pieces can be placed one after the other to define a set of items that must be 
present, or they can be separated by a vertical bar to indicate that one piece or the other must be present. 
Pieces can be grouped with parentheses into a larger atom. To match a literal parentheses, you must 
escape the character with a backslash. 

The regular expression (Tcl)|(Tk) will match either the string Tc] or the string Tk. The 
same strings would be matched by the regular expression T((cl)|k). The regular expression 
((Tc1) | (1k) |/)+ will match a set of Tcl, Tk, or slash. It would match the string Tcl, Tk, 
Tcl/Tk, Tk/Tcl, TclTk/, and so on, but not T1c-kT or other variants without a Tcl, Tk, or slash. 

The regular expression \([“ \)]*\) would match a parenthetical comment (like this). The back- 
slashed left parenthesis means to match a literal left parenthesis, then 0 or more characters that are not 
right parenthesis, and finally a literal right parenthesis. 


5.6.3 Advanced and Extended Regular Expression Rules 


This defines most of the basic regular expression rules. These features (with the exception of the bounds 
count modifier) are supported by all versions of Tcl. The 8.1 release of Tcl included a large number 
of modifications to the string handling. The largest change was to change the way strings were stored 
and manipulated. Prior to 8.1, Tcl used 8-bit ASCII for strings. With version 8.1, Tcl moved to 16-bit 
Unicode characters, giving Tcl support for international alphabets. 

Part of revamping how strings are handled required reworking the regular expression parser to han- 
dle the new-style character strings. Henry Spencer, who wrote the original regular expression library 
for Tcl also did the rewrite. While he was adding support for 16-bit Unicode he also added support for 
the Advanced and Extended regular expression rules. 

The rest of this discussion concerns the rules added in Tcl version 8.1. 
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Minimum and Maximum Match 
When the regular expression parser is looking for matches to rules, it may find multiple sets of 
characters that will match a rule. The decision for which set of characters to apply to the rule is: 


1. The set of characters that starts furthest to the left is chosen 
2. The longest set of characters that match from that position is chosen 


This behavior is referred to as greedy behavior. You can change this behavior to match the minimum 
number of characters by placing a question mark after the count modifier. For example, the following 
regular expression 


<.*> 


would match an HTML tag. It would work correctly with a string such as <IMG 
SRC="comic.gif">, but would match too many characters when compared to a string such as <IMG 
SRC="comic.gif"><P>. The greedy match is all characters between the first “<” and the last “>”, 
i.e., the entire string. 

Adding the question mark after the star will cause the minimal matching algorithm to be used, and 
the expression will match to a single HTML tag, as follows. 


<*> 


Internationalization 

Prior to Version 8.1, all Tcl strings were pure ASCII strings, and the content of a regular expres- 
sion would also be ASCII characters. Several new features were added to support the possible new 
characters. Unicode support is discussed in more detail in Chapter 12. 


Non-ASCII Values 

You can search for a character by its hexadecimal value by preceding the hex value with \x. For 
example, the « character is encoded as Oxe6 in hexadecimal, and could be matched using a script such 
as the following. 


% set s [format "The word salvi%c is Latin" Oxe6] 
% regexp {([* ]*x\xe6[* ]*)} $s ab 

1 

% puts $a 

salvia 


Character Classes, Collating Elements, and Equivalence Classes 

Another part of reworking the regular expression engine was to add support for named character 
classes, collating elements, and equivalence classes. These features make it possible to write a single 
regular expression that will work with multiple alphabets. 

A named character class defines a set of characters by using a name, instead of a range. For example, 
the range [A-Za- Zz] is equivalent to the named character class [[ : a1 pha: ]]. Anamed character class 
is defined by putting a square bracket and colon pair around the name of the character class. 

The advantage of named characters classes is that they automatically include any non-ASCII char- 
acters that exist in the local language. Using a range such as [A-Za-z] might not include characters 
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with an umlaut or accent. The named character classes supported by Tcl include those outlined in the 
following table. 


alpha The alphabetic characters 

lower — Lowercase letters 

upper Uppercase letters 

alnum — Alphabetic and numeric characters 
digit Decimal digits 

xdigit Hexadecimal digits 

graph _ All printable characters except blank 
cntr] Control characters (ASCII values < 32) 
space Any whitespace character 

< The beginning of a word 

> The end of a word 


A word is a set of alphanumeric characters or underscores preceded and followed by a non- 
alphanumeric or underscore character (such as a whitespace). 

A collating element is a multi-character entity that is matched to a single character. This is a 
way to describe two-letter characters such as e. A collating element is defined with a set of double 
square brackets and periods: [[. .]]. Thus, the Latin word salvie would be matched with the regular 
expression salvil[.ae.]]. 

An equivalence class is a way to define all variants of a letter that may occur in a language. It is 
denoted with a square bracket and equal sign. For example, [[=u]] would match to the character u, 
u, or U. Note that the internationalization features are only enabled if the underlying operating system 
supports the language that includes the compound letter. If your system does not support a collating 
element or equivalence class, Tcl will generate the following error. 


couldn’t compile regular expression pattern: invalid collating element 


Tcl Commands Implementing Regular Expressions 
Regular expression rules can be used for pattern matching with the switch and ]1search commands. 
Tcl also provides two commands for parsing and manipulating strings with regular expressions. 
regexp  Parses a string using a regular expression, may optionally extract portions 
of the string to other variables. 


regsub Substitutes sections of a string that match a regular expression. 


Syntax: regexp ?opt? expr string ?fullmatch? ?submatch? 
Returns | if expr has a match in string. If matchVar or subMatchVar 
arguments are present, they will be assigned the matched substrings. 


opt Options to fine-tune the behavior of regexp. Options 
include: 


exp 
str 
fu 


?Su 


-nocase 


-indices 


-line 
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Ignores the case of letters when searching for 
a match. 


Stores the location of a match, instead of 
the matched characters, in the submatch 
variable. 


Performs the match on a single line of input 
data. This is roughly equivalent to putting a 
newline atom at the beginning and end of the 
pattern. 


This option was added with Tcl release 8.1. 


Marks the end of options. Arguments that 
follow this will be treated as a regular expres- 
sion even if they start with a dash. 


r The regular expression to match with string. 


ing The string to search for the regular expression. 


T1match? If there is a match, and this variable is supplied to 
regexp, the entire match will be placed in this variable. 


bmatch? If there is a match, and this variable is supplied to reg- 
exp, the Nth parenthesized regular expression match will 
be placed in this variable. The parenthesized regular 
expressions are counted from left to right and outer to 


inner. 
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——— er eon 
Example 8 


Example Script 


Matc 
# fo 
# fo 
rege 
puts 
puts 
puts 
puts 
puts 


h a string of uppercase letters, 

llowed by a string lowercase letters 

llowed by a string uppercase letters 

xp {C(LA-Z]*)((La-z]*)[A-Z]*)} "ABCdefgHIU" abcde 


"The full match is: $a" 


"The first parenthesized expression matches: $b" 
"The second parenthesized expression matches: $c" 
"The third parenthesized expression matches: $d" 
"There is no fourth parenthesized expression: $e" 


Script Output 


The 
The 
The 
The 


full match is: ABCdefgHIJ 


first parenthesized expression matches: ABC 


second parenthesized expression matches: defgHIJ 


third parenthesized expression matches: defg 


There is no fourth parenthesized expression: 
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Syntax: regsub ?options? expression string subSpec varName 
Copies string to the variable varName. If expression matches a portion of 
string, that portion is replaced by subSpec. 
options Options to fine-tune the behavior of regsub. 

May be one of: 

-all Replaces all occurrences of the reg- 
ular expression with the replace- 
ment string. By default, only the 
first occurrence is replaced. 

-nocase Ignores the case of letters when 
searching for match. 

=e Marks the end of options. Argu- 
ments that follow this will be treated 
as regular expressions, even if they 
start with a dash. 

expression A regular expression that will be compared with 
the target string. 


string A target string with which the regular expression 
will be compared. 
subSpec A string that will replace the regular expression 
in the target string. 
varName A variable in which the modified target string 
will be placed. 
FB] $$_$_[?€_ 


Example 9 
regsub Example 
set bad "This word is spelled wrung" 


regsub "wrung" $bad "correctly" good 
puts $good 


Script Output 

This word is spelled correctly 

ct 

The portions of a string that match parenthesized atoms of a regular expression can also be captured 
and substituted with the regsub command. The substrings are named with a backslash and a single 
digit to mark the position of the parenthesized atom. As with the regexp parenthesized expressions, 
they are numbered from left to right, and outside to inside. The subexpressions are numbered starting 
with \1, with \0 being the entire matching string. 


———oo——_ smh ek = axe 
Example 10 


regsub Example 


set wrong {Don’t put the horse before the cart} 
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regsub {(D[*r]*x)(hL* Jx)( +£*c]*)(c.*)} $wrong \ 
{\1\4\3\2\} right 
puts $right 


Script Output 


Don’t put the cart before the horse 


The regular expression (D[*rJ*)(h[*% ]*)( +[%c]*)(c.*)} breaks down to the following. 


Piece Description Matches 
(DEArI]*) A set of characters starting with D and including Don’t put the 
any character that is not an r 
Ch[* J*) A set of characters starting with h and including horse 
any character that is not a space 
( +[4c]*) One or more spaces, followed by a set of before the 
characters that are not c 
(c.*) A set of characters starting with c, followed by cart 
one or more of any character until the end of the 
string 


The substitution phrase {\1\4\3\2} reorders the piece such that the first piece is followed by the 
fourth (cart), and the second piece (horse) becomes the last. 


.4 Back to the Searching URLs 


We could use the regexp command in place of the string or 1search commands to search for 
Noumena . This code would resemble the following. 


————oooooo OO —-—n—n eee 
Example 11 


Search Using a regexp Test 


foreach item $urlList { 
if {Lregexp {[NnJoumena} $item]} { 
puts "NOUMENA PAGE:\n$item" 
} 
} 


Script Output 
NOUMENA PAGE: 
www.noucorp.com "Noumena Corporation" 


Alternatively, we could just use the regexp command to search the original text for a match rather 
than the text converted to a list. This saves us a processing step. 
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7s——__A 
Example 12 
Search All Data Using regexp 

set found [regexp "(\[7\nJ«*\ENn\Joumena\[*\nJ]*)" $uris\ 

fullmatch submatch] 

if {$found} { 

puts "NOUMENA PAGE:\n $submatch" 

} 


Script Output 
NOUMENA PAGE: 
www.noucorp.com "Noumena Corporation" 


Let’s take a careful look at the regular expression in Example 12. 

First, the expression is grouped with quotes instead of braces. This is done so that the Tcl inter- 
preter can substitute the \n with a newline character. If the expression were grouped with braces, the 
characters\n would be passed to the regular expression code, which would interpret the backslash as a 
regexp escape character and would look for an ASCII n instead of the newline character. 

However, since we have enclosed the regular expression in quotes, we need to escape the braces 
from the Tcl interpreter with backslashes. Otherwise, the Tcl interpreter would try to evaluate [*\n] 
as a Tcl command in the substitution phase. Breaking the regular expression into pieces, we have: 


[A\n]* Match zero or more characters that are not newline characters 
[LNnJoumena Followed by the word Noumena or noumena 


[“\n]* Followed by zero or more characters that are not newline characters 


This will match a string that includes the word Noumena and is bounded by either newline char- 
acters or the start or end of the string. If regexp succeeds in finding a match, it will place the entire 
matching string in the ful ]match variable. The portion of the string that matches the portion of the 
expression between the parentheses is placed in submatch. If the regular expression has multiple sets 
of expressions within parentheses, these portions of the match will be placed in submatch variables in 
the order in which they appear. 

The regexp command in recent versions of Tcl supports a - 1 ine option. The -1ine option will 
limit matches to a single line. Using this option, we do not need the \n to mark start and end of the line, 
so we can simplify the regular expression by using curly braces instead of quotes, and simple atoms 
instead of ranges for the character matches, as follows. 


set found [regexp -line {(.*[NnJoumena.*)} \ 
$urls fullmatch submatch ] 


Adding the -nocase option will further simplify the regular expression, as follows. 


set found [regexp -line -nocase {(.*noumena.*)} 
$urls fullmatch submatch ] 
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Alternatively, we could use the submatching support in regexp to separate the URL from the 
description, as follows 


—————— eee eee 
Example 13 


Script Example 


set found [regexp —line —nocase {(.*) +(.*noumena.*)} \ 
$urls full url desc] 
if {$found} { 
puts "full: $full" 
puts “url: $url" 
puts "desc: $desc" 


} 
Script Output 


full: www.noucorp.com "Noumena Corporation" 
url: www.noucorp.com 
desc: "Noumena Corporation" 


CREATING A PROCEDURE 


Identifying one datum in a set of data is an operation that should be generalized and placed in a 
procedure. This procedure is a good place to reduce the line of data to the information we actually want. 


The proc Command 


A Tcl subroutine is defined with the proc command and thus is commonly called a proc. 

The proc command takes three arguments that define a procedure: the procedure name, the argu- 
ment list, and the body of code to evaluate when the procedure is invoked. When the proc command 
is evaluated, it adds the procedure name, arguments, and body to the list of known procedures. The 
command looks very much like declaring a subroutine in C or Fortran, but proc is a command that 
modifies the procedure table when it is evaluated, not a declaration that will be evaluated before the 
rest of the code. Procedures must be created with the proc command before they can be used. 


Syntax: proc name args body 
Create a new procedure and add it to the procedure list 


name The name of the new procedure 

args A list of arguments for the new pro- 
cedure (commonly enclosed in curly 
brackets) 

body The body of the new procedure (com- 
monly enclosed in curly brackets) 
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eee 
Example 14 


Script Example 


it Define a proc 
proc demoProc {argl arg2} { 
puts "demoProc called with $argl and $arg2" 


} 

i## Now, call the proc 
demoProc 1 2 

demoProc alpha beta 


Script Output 
demoProc called with 1 and 2 
demoProc called with alpha and beta 


5.7.2 A findUr1 Procedure 


This proc will find a line that has a given substring, extract the URL from that string, and return just 
the URL. It can accept a single line of data or multiple lines separated by newline characters. 


—_—_—_—_—_—_—_—_—_—_—_—_—_—_—  &€_ <—<—o—_—_—_—_—_——S—X—: 
Example 15 


Script Example 


dt findUrl — 

if Finds a particular line of data in a set of lines 
if Arguments: 

i## match A string to match in the data 

i# =o text Textual data to search for the pattern. 


i Multiple lines separated by newline 
if characters. 
i## «Results: 
i## Returns the line which matched the target string 
i 
proc findUrl {match text} { 
set url "" 


set found [regexp —line —nocase \ 
"C.e) +(.e$match.«*)" $text full url desc] 
return $url 
} 
i## Invoke the procedure to 
## search for a couple of well known sites 
i 


puts "Noumena site: [findUrl Noumena $urls]" 
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puts "Tcl Community site: [findUrl Community $urls] 
if {Lstring match [findUrl noSuchSite $urls] ""J} { 
puts "noSuchSite not found" 


} 


Script Output 
Noumena site: www.noucorp.com 
Tcl Community site: www.tclcommunityassociation.org 
noSuchSite not found 


Variable Scope 


Most computer languages support the concept that variables can be accessed only within certain scopes. 
For instance, in C, a subroutine can access only variables that are either declared in that function (local 
scope) or have been declared outside all functions (the extern, or global, scope). 

Tcl supports the concept of local and global scopes. A variable declared and used within a proc 
can be accessed only within that proc, unless it is made global with the global command. The Tcl 
scoping rules are covered in detail in Chapters 7 and 8. 

Tcl also supports namespaces, similar in some ways to the FORTRAN named common (a set of 
variables that are grouped) or a C++ static class member. The namespace command is discussed in 
Chapter 8. 

Global variables must be declared in each procedure that accesses a global variable. This is the 
opposite of the C convention in which a variable is declared static and all functions get default access 
to that variable. The global command will cause Tcl to map a variable name to a global variable, 
instead of a local variable. 


Syntax: global varNamel varName2... 
Map a variable name to a global variable. 
varName*x The name of the variable to map 


eee 
Example 16 


Script Example 


set al 

set b 2 

proc tst {} { 
global a 
set a "A" 
set b "B" 


puts "$a $b" 
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Script Output 
% tst 
AB 
% puts "$a $b" 
A2 


Within the proc tst the variable a is mapped to the a in the global scope, whereas the variable b 
is local. The set commands change the global copy of a and a local copy of b. When the procedure is 
complete, the local variable b is reclaimed, while the variable a still exists. The global variable b was 
never accessed by the procedure tst. 


5.7.4 Global Information Variables 


Tcl has several global variables that describe the version of the interpreter, the current state of the 
interpreter, the environment in which the interpreter is running, and so on. Some of these variables are 
simple strings or lists, and some are associative arrays. Associative arrays will be discussed in more 
detail in the next chapter. The information variables include the following. 


argv A list of command line arguments. 

argc The number of list elements in argv. 

env An associative array of environment variables. 

tcl_version The version number of a Tcl interpreter. 

tk_version The version number of the Tk extension. 

tcl_pkgPath A list of directories to search for packages to load. 

erroriInfo After an error occurs, this variable contains information about 
where the error occurred within the script being evaluated. 

errorCode After an error occurs, this variable contains the error code of the 
error. 

tcl_platform An associative array describing the hardware and operating sys- 


tem the script is running under. The tcl_platform associative 
array has several indices that describe the environment the script 
is running on. These indices include: 


user The username of the user running the interpreter. 


byteOrder The order of bytes on this hardware. Will be 
LittleEndian or BigEndian. 


osVersion The version of the OS on this system. 
machine The CPU architecture (i386, sparc, and so on). 


platform The type of operating system. Will be macintosh, 
unix, or windows. 
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os The name of the operating system. On a UNIX 
system this will be the value returned by uname 
-S. For MS Windows systems it will be Windows 
NT, or Windows 95. Microsoft Windows 
platforms are identified as the base version of the 
OS. Windows 2000 is identified as Windows NT, 
and Windows 98 and ME are identified as 
Windows 95. 

New array indices have been added in Tcl8.5 and Tcl8.6. These include: 
threaded Will be 1 if the interpreter is compiled 
with threading enabled, else 0 


pointerSize The size of a pointer on this machine. 
wordSize The size of a word on this machine. 


5.8 MAKING A SCRIPT 


As a final step in this set of examples, we will create a script that can read the bookmark file of a well- 
known browser, extract a URL that matches a command line argument string, and report that URL. 
This script will need to read the bookmark file, process the input, find the appropriate entry or entries, 
and report the result. Because the bookmark files are stored differently under UNIX, Mac OS, and MS 
Windows, the script will have to figure out where to look for the file. 

We will use the tcl_platform global variable to determine the system on which the script is 
running. Once we know the system on which the script is running, we can set the default name for the 
bookmark file, open the file, and read the content. 


5.8.1 The Executable Script 


Aside from those additions, this script uses the code we have already developed. 


HMMM MC MMMM aaa 
## geturl.tcl 

# Clif Flynt -- clif@cflynt.com 

dt 

## Extracts a URL from a mozilla/firefox bookmark file 

dt 

HMMM MMNIN Ui inhale 
dt findUrl - 

if Finds a line in the text string that matches the 

## pattern string. Extracts the URL from that line. 

dt 

dt Arguments: 

## match The pattern to try and match 

if text The string to search for a match in. 
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fl 
if Results: 
i## Returns the matched URL, or "" 
proc findUrl {match text} { 
set url "" 
set expression [format {"http://(.*2?%s.*?)"} $match] 
regexp -line -nocase $expression $text full url 
return $url 
} 
MMMM tt iiiiMtiiiiiiiiiinnninnanaaaad 
fl 
if Check for a command line argument 
fl 
if {$arge != 1} { 
puts "geturl.tcl string" 
exit -1; 
} 


il 
i## Find a Firefox bookmark file. 
i## The path to this file depends on the platform and operating system. 
i 
switch $tcl_platform(platform) { 
unix { 
## unix could be Linux, Darwin, Solaris or something else. 
switch $tcl_platform(os) { 
Darwin { 
set paths [glob [file join $env(HOME) Library \ 
"Application Support" Firefox Profiles *default bookmarks.html]] 
set bookmarkName [lindex $paths end] 


} 
Linux { 
set paths [glob [file join $env(HOME) .mozilla firefox \ 


*xdefault bookmarks.html J] 
set bookmarkName [lindex $paths 0] 


default { 
set paths [glob [file join $env(HOME) .mozilla firefox \ 


xdefault bookmarks.html J] 
set bookmarkName [lindex $paths 0] 


} 
} 
windows { 
set paths [glob [file join C:/ "Documents and Settings" $env(USERNAME) \ 
"Application Data" Mozilla Firefox Profiles *.default bookmarks.html J] 
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set path Llindex [glob $paths] 0] 
d## Strip potential { and } from the name returned by glob. 
set bookmarkName [string trim $path "{}"] 
} 
mac - 
macintosh { 
if Mac OS 8, 9 - No Firefox, look for an old Netscape bookmark file. 
if Find the exact path, with possible unprintable characters. 
set path [file join $env(PREF FOLDER) Netsc* * Bookmarks.html ] 
# If there are multiple personalities, return just one file 
set path [lindex [glob $path] 0] 
# Strip potential { and } from the name returned by glob. 


set bookmarkName [string trim $path "{}"] 
} 
default { 
puts "I don recognize platform: $tcl platform(platform)" 
exit -l; 
} 
} 
tf 
## Open the bookmark file, and read in the data 
i 


set bookmarkFile [Lopen $bookmarkName ] 
set bookmarks [read $bookmarkFile] 
close $bookmarkFile 


puts LfindUrl $argv $bookmarks ] 


5.9 SPEED 


One question that always arises is “How fast does it run?” This is usually followed by “Can you make 
it run faster?” The time command times the speed of other commands. 


Syntax: time cmd ?iterations? 
Returns the number of microseconds per iteration of the command. 
cmd The command to be timed. Put within curly braces if you 
do not want substitutions performed twice. 


?iterations? The number of times to evaluate the command. When 
this argument is defined, the t ime command returns the 
average time for these iterations of the command. 


The time command evaluates a Tcl command passed as the first argument. The cmd argument 
will go through the normal substitutions when time evaluates it, so you probably want to put the cmd 
variable within curly braces. We have tried several methods of extracting a single datum from a mass 
of data. Now, let’s look at the relative speeds, as depicted in the following illustration. 
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Regexp in proc 

Regexp 

Lsearch with split 

Lsearch list 

oreach string match in proc && 
Foreach string match 
Foreach string first in proc 
Foreach string first 
Foreach regexp 
For string match in proc 
For string match 
For string first in proc 
For string first 


10.00 20.00 .00 40.00 .00 60.00 70.00 80.00 90.00 100.00 110.00 120.00 
Time in microseconds 


84 985 986 


5.9.1 Comparison of Execution Speeds (Linux Celeron @ 2.6 GHz) 


The graph shows execution time in microseconds of various ways to find the Noumena url in the list of 
urls. Notice that a foreach loop is faster than a for loop for processing a list of data. This is because 
using the foreach loop doesn’t require an extra 1 index step to extract the list element being tested. 
Placing code inside a procedure will also speed it up. The procedures are byte-code compiled the first 
time they are used and the faster byte-code compiled version is retained for future use. 

Regular expressions are very powerful, but are generally slower than simple string or list search 
commands. The first step in using a regular expression is to compile the expression into an internal 
format, and that can be expensive. 

If you can search your entire set of data with a single 1search or regexp command that will be 
faster than iterating through a loop. 

Finally, these timing tests were accurate when I ran them. The Tcl interpreter is always being 
improved, either with new features or new optimizations. Some new features will make the interpreter 
slower but more powerful until the next round of optimizations. If speed and performance are truly 
an issue for you, you should run your own tests and consider rewriting the more compute intensive 
sections of your application in C as described in Chapters 15 and 18. 


5.10 BOTTOM LINE 


There are some tricks in Tcl that may not be apparent until you understand how Tcl commands are 
evaluated. 


e Tcl variables exist in either a local or global scope, or can be placed in private namespaces. 
e A Tcl procedure may execute in its default scope or in the scope of a procedure in its call tree. 
e Searching a list with 1search is faster than iterating through a list, checking each item. 
e The time command can be used to tune your code. 
Syntax: time cmd ?iterations? 
e Regular expression string searches are performed with the regexp command. 
Syntax: regexp?opt? expr str ?fullmatch? ?submatch? 
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e Regular expression string substitutions are performed with the regsub command. 
Syntax: regsub?opt? expr str subSpec varName 
e You can search a set of data for items matching a pattern with: 
Syntax: string match pattern string 
Syntax: string first pattern string 
Syntax: string last pattern string 
Syntax: |search list pattern 
Syntax: regexp ?opt? expr str ?fullmatch? ?submatch? 


5.11 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5 line script. These problems should each take under a 
minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e¢ 100 Some operations are well suited to a for loop, whereas others are better suited to a foreach 
or while loop. Which loop construct is best suited to each of the following operations? 
e Calculating the Y coordinate for a set of experimentally derived X values 
e Calculating the Y coordinate for X values between 1 and 100 
e Examining all files in a directory 
e Scanning a specific port on a subnetwork to find systems running software with security holes 
e Waiting for a condition to change 
e Inverting a numerically indexed array 
e Jterating through a tree 
e Reversing the order of letters in a string 


e 10] Can you use a single 1search command to find two adjacent elements in a list? 
e 102 Can you use an 1Search command to find the third occurrence of a pattern in a list? 


e 103 What regular expression atom will match the following? 
e One occurrence of any character 
e One occurrence of any character between A and L 
e One occurrence of any character except Q 
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The word Tcl 
e A single digit 


e 104 Given the following Tcl command: 
regexp $exp $s full first 
with the variable s assigned the string “An image is worth 5 x 103 pixels,” what string would be 
assigned to the variable first for the following values of exp? 
{({0-9]+)} 
© {({0-9]{2})} 
© (AP) 40> Po 
© {(w.* E>] D} 


e 105 What global variable contains a list of command line arguments? 


e 106 What global variable can be used within a script to discover if the script is being evaluated on 
a Windows or UNIX platform? 


e 200 The 1search command will return the index of the first match to a pattern. Write a one-line 
command (using square brackets) to return the first list element that matches a pattern, instead of 
the index. 


e 20] Write an |Search command that would find the element that: 

e Starts with the letter A and has other characters 

e Starts with the letter A followed by 0 or one integer 
Starts with the letter A followed by 1 or more integers 

e Starts with the letter A followed by | or more integers, with the final integer either 0 or 5 
Is a number between 0 and 199 

e Isastring with 5 characters 

e Isastring with less than 3 characters 


e 202 Write a regexp command that will extract the following substrings from the string ’Regular 
expressions are useful and powerful”. Note that these substrings can be matched by a 
regular expression that is not a set of atoms identical to the substring. 

Regular expressions are us 
e expressions 
° pow 
e useful and powerful 


e 203 Write a regexp command that will extract: 
e The first word from a string 
The second word from a string 
e A word with the letters ss in it 
A word of 2 to 4 letters long 


¢ 300 Write a Tcl procedure that will split a set of data into a list on multi-character markers, instead 
of the single-character marker used by 1 search. For example, this procedure should split 
aaaSPLITbbbSPLITcccSPLITddd into the list {aaa bbb ccc ddd}. 
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30] Write a procedure that will accept a list and return the longest element in that list. 


302 The 1search command will return the index of the first match to a pattern. Write a procedure 
that will return the index of the Nth match. The procedure should accept a list, pattern, and integer 
to define which match to return. 


303 Modify the procedure from the previous exercise to return the Nth list element that matches a 
pattern, instead of the Nth index. 


304 Write a procedure that will accept a list and two patterns and return a list of the indices for the 
element that matches the first pattern followed by the element that matches the second pattern. 


305 Modify the procedure from the previous exercise to return the indices of the elements that 
match the two patterns when the elements are adjacent. This may not be the first occurrence of 
either element. 


CHAPTER 


Complex Data Structures 
with Lists, Arrays and Dicts 


This chapter demonstrates how lists, arrays and dicts can be used to group data into constructs similar 
to C structs, linked lists, and trees. Tcl has been accused of being unsuited for serious programming 
tasks because of the simplicity of its data types. Whereas Java has integers, floats, pointers, structs, and 
classes, Tcl had only strings, lists and associative arrays. The 8.5 release added the dict data structure 
to Tcl, and 8.6 adds classes and more. The simple constructs are frequently sufficient. This chapter will 
show some techniques for using Tcl data constructs in place of the more traditional structs, linked lists, 
and so on. 

The first examples show how lists can be used to group data in ordered and unordered formats, then 
using keyed lists and simple dicts to collect sparse or duplicated data. The next section explores using 
associative arrays instead of structs. The final set of examples shows how dicts can be used with nested 
data sets. 

The last section discusses Tcl’s support for interacting with SQL databases. The Tcl dict provides 
a good data structure for this interaction since it can reflect whether a value is NULL or is present but 
empty. 

If you are familiar with compiled languages such as C or Pascal, you may want to consider why 
you use particular constructs in your programs instead of others. Sometimes, you may do so because of 
the machine and language architecture, rather than because the problem and the data structure match. 
In many cases the Tcl data types solve the problem better than the more familiar constructs. 

For example, when programming in compiled languages such as C or Pascal, there are several 
reasons for using linked lists. 


e Linked lists provide an open-ended data structure; you do not need to declare the number of entries 
at compile time. 

e Data can be added to or deleted from linked lists quickly. 

e Entries in a linked list can be easily rearranged. 

e Linked lists can be used as container classes for other data. 


The Tcl list supports all of these features. In fact, the internal implementation of the Tcl list allows 
data items to be swapped with fewer pointer changes than exchanging entries in a linked list. This 
allows commands such as 1 sort to run very efficiently. 

The important reason for using linked lists is that you can represent the data as a list of items. 
The Tcl list is ideal for this purpose, allowing you to spend your time developing the algorithm for 
processing your data, instead of developing a linked list subroutine library. 

A binary tree is frequently used in C or Pascal to search for data efficiently. The Tcl interpreter 
stores the indices of an associative array in a very efficient hash table. Rather than implementing 
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a binary tree for data access purposes, you can use an associative array and get the speed of a good 
hash algorithm for free. As a tree grows deeper, the hash search becomes faster than a binary search, 
without the overhead of balancing the tree. 

Most applications that use Tcl are not speed critical, and the speed of the list or array is generally 
adequate. If your application grows and becomes speed bound by Tcl data constructs, you can extend 
the interpreter with other faster data representations. Extending the interpreter is covered in Chapter 15. 


6.1 USING THE TCL LIST 

A Tcl list can be used whenever the data is conceptualized as a sequence of data items. These items 
could be numeric (such as a set of graph coordinates) or textual, such as a list of fields from a database 
or even another list. 


| a | 


6.1.1 Manipulating Ordered Data with Lists 


Lists can be used to manipulate data in an ordered format. Spreadsheet and database programs often 
export data as strings of fields delimited by a field separator. The Tcl list is an excellent construct for 
organizing such data within a program. Each spreadsheet row can be a separate list element consisting 
of the row data. As the rows are processed, the elements can be extracted into a set of variables with 
the 1assign command or extracted as needed with the | index command. 


Syntax: lassign list varNamel varName2 
Extracts N elements from a list and assigns their values to N variables. 
list The list to extract values from. 


varNamex A set of variables to extract values into. 


Using the 1assign command to extract the values of a list in a single command improves code 
maintenance, since all of the field definitions are in one line of code. 

If you need to split the field access across several areas of code, the code maintenance becomes 
simpler if you use a set of variables to define the locations of the fields in a list, rather than hard-coding 
the positions in the 1 index commands. The mnemonic content of the variable names makes the code 
more readable. This technique also allows you to add new fields without having to go through all your 
code to change hard-coded index numbers. 

Chapters 3 and 5 showed how a comma-delimited line could be split into a Tcl list, with each field 
becoming a separate list element. The next example manipulates three records with fields separated 
by colons, similar to data exported by a spreadsheet or saved in a system configuration file (such as 
/etc/passwd). 

In this example, each record has four fields in a fixed order: unique key, last name, first name, 
and e-mail address. The example converts the records to lists with the split command and then 
merges the lists into a single list with the 1append command. After the data has been converted to a 
list, the 1search command is used to find individual records in this list, the 1 replace command 
is used to modify a record, and then the list is converted back to the original format. The join 
command is the flip side of the split command. It will join the elements of a list into a single 
string. 


6.1 Us 


Syntax: join Jist ?joinString ? 
Join the elements of a list into a single string. 


list 


?joinString? 


The list to join into a string. 
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Use this string to separate list elements. Defaults to a 


space. 


The 1 replace command will replace one or more list elements with new elements or can be used 


to delete list elements. 


Syntax: lreplace list first last ?elementl element2 


at 


Return a new list, with one or more elements replaced by zero or 
more new elements. 


list 
first 
last 
element* 


The original list. 


The position of the first element in the list to be replaced. 
The position of the last element in the list to be replaced. 


A list of elements to replace the original elements. If this list is 


shorter than the number of fields defined by first and last, 
elements will be deleted from the original list. 


________ o_o ooo 


Example 1 


Position-oriented Data Example 


if Define textual 
set text { 


data 


KEY1:Flynt:Clif:clif@cflynt.com 
KEY2:Doe:John: jxd@example.com 
KEY3:Doe:Jane: janed@example.com 


} 
## Set up a list 


foreach line [split $text \n] { 


dt Skip any blank lines 
if {$line eq ""} { 


continue 

} 

lappend data [split $line :] 
} 
# data is a list of lists. 
dt 
dt { {KEY1 Flynt Clif clif@cflynt.com} 
if {KEY2 Doe John jxd@example.com} ...} 
i## Assign the record posi 


set keyIndex 0; 
set lastNameIndex 1; 


tions to mnemonically named variables 


148 CHAPTER 6 Complex Data Structures with Lists, Arrays and Dicts 


set firstNameIndex 2; 
set eMailIndex 3; 


if Find the record with KEY2 
set position [lsearch $data "KEY2 «"] 


i## Extract a copy of that record 
set record Llindex $data $position] 


i## Display fields from that record 

puts "The Email address for Record [Llindex $record $keyIndex] \ 
(Llindex $record $firstNameIndex]) was \ 
Llindex $record $eMailIndex] " 


if Modify the eMail Address 
set newRecord [lreplace $record $eMailIndex $eMailIndex \ 
"joed@example.com" J 


## «Confirm change 

puts "New Email address for Record [lindex $newRecord $keyIndex] \ 
(Llindex $newRecord $firstNameIndex]) is \ 
Llindex $newRecord $eMailIndex] " 


it Update the main list 
set data [lreplace $data $position $position $newRecord] 


i## Convert the list to colon—delimited form, and display it. 
foreach record $data { 
puts "“[Ljoin $record :]" 


} 


Script Output 
The Email address for Record KEY2 (John) was jxd@example.com 
The Email address for Record KEY2 (John) is joed@example.com 
KEY1:Flynt:Clif:clif@cflynt.com 
KEY2 : Doe: John: joed@example.com 
KEY3 :Doe: Jane: janed@example.com 


6.1.2 Manipulating Data with Keyed Lists 


In some applications information may become available in an indeterminate order, some fields may 
have multiple sets of data, and some fields may be missing. It may not be feasible to build a fixed- 
position list for data such as this. For example, the e-mail standard does not define the order in which 
header fields must occur, some fields (such as Subj ect) need not be present and there may be multiple 
Received fields. 
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One solution to representing data such as this is to use a string to identify each piece of data and 
create pairs of identifier and data. As the data becomes available, the identifier/data pair is appended to 
the list. 

Since a Tcl list can contain sublists, you can use the list to implement a collection of key/value 
pairs. The records in the next example consist of two-element lists. The first element is a field iden- 
tifier, and the second element is the field value. The order of these key/value pairs within a record is 
irrelevant. There is no position-related information, because each field contains an identifier as well 
as data. 

The keyed list data structure is supported in the tc1X extension. It can also be implemented with a 
few simple procedures. The dict data structure is a more extensive implementation of the keyed list 
concepts. It will be described in the next section. 

The following example shows a set of procedures to store and retrieve data in a keyed list. The 
sample script places information from an e-mail header into a keyed list, and then retrieves portions of 
the data. 


-— 
Example 2 
Keyed Pair List Procedures 
MMMM Maa aaa aaa 
## proc keyedListAppend {list key value} 
if Return a list with a new key/value element at the end 
if Arguments 
if list: Original list 
if ey: Key for new element 
i value: Value for new element 
proc keyedListAppend {list key value} { 
lappend list [list $key $value] 
return $list 


} 
MMMM aa aaa aaa 
## proc keyedListSearch {list keyName} 


if Retrieve the first element that matches $keyName 
if Arguments 
if list: The keyed list 


if keyName: The name of a key 

proc keyedListSearch {list keyName} { 
set pos [lsearch $list "$keyNamex" ] 
return Llindex Llindex $list $pos] 1] 


} 
MMMM Maa aaa 
## proc keyedListRetrieve {list keyName} 


if Retrieve all elements that match a key 
if Arguments 

if list: The keyed list 

if keyName: The name of key to retrieve 


# 
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proc keyedListRetrieve {list keyName} { 
set start 0 
set pos [lsearch [lrange $list $start end] "${keyName}x«" ] 
while {$pos >= O} { 
lappend locations [expr $pos + $start] 
set start [expr $pos + $start + 1] 
set pos [Llsearch [lrange $list $start end] "${keyName}x" ] 
} 
foreach 1 $locations { 
lappend rtn [Llindex [lindex $list $1] 1] 
} 


return $rtn 


Using the Keyed Pair Procedures 


i## Define a simple e-mail header 

set header { 

Return—Path: <root@firewall.example.com; 
Received: from firewall.example.com 
Received: from mailserver.example.com 
Received: from workstation.noucorp.com 
Date: Tue, 6 Aug 2002 04:13:38 —0400 
Message-Id: <200208060813.g768DcP30231> 
From: root@firewall.example.com (Cron Daemon) 
To: root@firewall.workstation.com 
Subject: Daily Report 

} 


## Initialize a keyed list 
set keyedList "" 


if Parse the e-mail header into the keyed list. 


if The first ":" marks the key and value for each line. 
df 

i## Note that [split $line :] won’t work because of lines 
if with timestamps. 


foreach line [split $header \n] { 
set p [string first : $line] 
if {$p < 0} {continue} 
set key [string range $line 0 [expr {$p — 1}]] 
set value [string range $line [expr {$p + 2}] end] 
set keyedList [keyedListAppend $keyedList $key $value] 


} 


if Extract some data from the keyed list 
puts "Mail is from: [keyedListSearch $keyedList From]" 
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puts "Mail passed through these systems in this order:" 
foreach r [keyedListRetrieve $keyedList Received] { 
puts " Llindex $r 1]" 


Script Output 
Mail is from: root@firewall.example.com (Cron Daemon) 
Mail passed through these systems in this order: 
firewall.example.com 
mailserver.example.com 
workstation.noucorp.com 


For most lists, this technique works well. However, the time for the 1search command to find an 
entry increases linearly with the position of the item in the list. Lists longer than 1,000 entries become 
noticeably sluggish. The pairing of data to a key value can also be done with dicts or associative arrays. 
Dicts and arrays use hash tables instead of a linear search to find a key, so the speed does not degrade 
as more records are added. 


6.2 USING THE DICT 


The dict command was added to Tcl in version 8.5. Conceptually, the dict is very similar to the keyed 
list. Internally, it uses many of the same code constructs as the associative array, making it both fast 
and efficient. 

The keyed list example shown above parsed an email header. This example can be easily reworked 
to use a dict instead of a keyed list, as shown below. 


ooo —_:.”—nmnknknk Eee 
Example 3 


## Define a simple e-mail header 
set header { 
Return—Path: <root@firewall.example.com; 
Received: from firewall.example.com 

Received: from mailserver.example.com 
Received: from workstation.noucorp.com 

Date: Tue, 6 Aug 2002 04:13:38 —0400 
Message-Id: <200208060813.9768DcP30231> 

From: root@firewall.example.com (Cron Daemon) 
To: root@firewall.workstation.com 

Subject: Daily Report 

} 


if Parse the e-mail header into the keyed list. 
if The first ":" marks the key and value for each line. 


152 CHAPTER 6 Complex Data Structures with Lists, Arrays and Dicts 


df 
## Note that [split $line :] won’t work because of lines 
i with timestamps. 


foreach line [split $header \n] { 
set p [string first : $line] 
if {$p < 0} {continue} 
set key [string range $line 0 [expr {$p — 1}]] 
set value [string range $line [expr {$p + 2}] end] 
dict lappend keyedList $key $value 


} 


jf Extract some data from the keyed list 
puts "Mail is from: [dict get $keyedList From]" 
puts "Mail passed through these systems in this order:" 
foreach r [dict get $keyedList Received] { 
puts " [Llindex $r 1]" 
} 


Script Output 
Mail is from: root@firewall.example.com (Cron Daemon) 
Mail passed through these systems in this order: 
firewall.example.com 
mailserver.example.com 
workstation.noucorp.com 


With this short dataset, the dict version of the example runs in about 60% of the time that it takes 
the keyed list version to run. As the data set gets larger, the improved speed of the dict becomes more 
significant. 


6.2.1 Grouping Related Values 


Many languages support a data structure for grouping information. In “C” this is the struct, and in 
Pascal it’s called a record. Arrays of structs are commonly used to hold collections of related informa- 
tion. For example, within the operating system, memory segments and file descriptors are maintained 
as arrays of structs each of which defines a specific area of memory or open file. 

The dict command can provide this functionality in Tcl. 


C Structure Tcl Dict 

struct { set var [dict create \ 
int value; value 1 desc "One" J 
char desc[80]; 

} var; 


var.value = 1; 
strcpy(var.desc,"One"); 
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An enumerated array of structures can also be created with the dict command like this: 


Array of C Structures Tcl Dict 
struct { set var [dict create \ 

int value; 0 [dict create \ 

char desc[80]; value 1 desc "One" ] \ 
} varL5]; 1 [dict create \ 


value 2 desc "Two" ] 
varLO].value = 1; J 
strcpy(var[L0].desc, "One"); 


var[l].value = 2; 
strcpy(var[l].desc, "Two"); 


New values can be added to an existing dict with the dict set command or the dict lappend 
or dict append commands as shown below. 


3-—_—_AAASA\\ADP>YN}? A 
Example 4 
Adding Elements to a Dict 
## Define a dict with 2 elements 
set var [dict create \ 
0 [dict create value 1 desc "One"] \ 
1 [dict create value 2 desc "Two"] \ 
] 
it Add a new element 2 
dict set var 2 [dict create val 3 desc three] 


it Add element 3 using lappend 
dict lappend var 3 val 4 desc Four 


it Add element 4 using append 
dict append var 4 [dict create val 5 desc Five] 


## Print the value for element 3 
puts "The value for element 3 is [dict get $var 3 val]" 


Script Output 


The value for element 3 is 4 
=| 


Using numbers to distinguish elements in a dictionary works, but may require a second layer of 
mapping concepts to values. Unlike a “C” struct or Pascal record, the key for a dict element can be 
textual and thus have information content other than just the element position. 

The next example shows how a set of data can be represented in “C” and with a Tcl dict. 
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Here is a table of gemstone color and hardness. 


Agate Brown 7.0 
Amethyst Purple 7.0 


Aquamarine Blue 75 


The next example is a “C” program to store and display this data. 


Oooo. —n—nknknkn Eee 
Example 5 


Saving Data in an Array of “C” Structs 


#Hinclude <stdio.h> 
#Hinclude <strings.h> 


main () { 
struct { 
char name[20]; 
char color[10]; 
float hardness; 
} gems[3]; 


Tnt 13 


strcpy(gems[O0].name, "Agate"); 
strcpy(gems[1l].name, "Amethyst"); 
strcpy(gems[2].name, “Aquamarine"); 


strcpy(gems[0].color, "Brown"); 
strcpy(gems[l].color, “Purple"); 
strcpy(gems[2].color, "Blue"); 


ll 


gems[0].hardness 
gems[1].hardness 
gems[2].hardness 


ll 
NNN 
aoe 


ll 


for (i = 0; i < 3; i++) { 
printf("%s is colored 4s with %.1f hardness\n", \ 
gemsLi].name, gems[i].color, gems[i].hardness); 


When compiled and run this program generates the following output: 


Agate is colored Brown with 7.0 hardness 
Amethyst is colored Purple with 7.0 hardness 
Aquamarine is colored Blue with 7.5 hardness 
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An array of structs has no obvious relationship between the key to the data (the numeric index) 
and the contents. This makes it difficult to maintain this type of code. It’s not obvious that the 
hardness value of 7.5 is connected to the name value Aquamarine unless you look at the index 
values. 

The next example shows how this data can be represented in a dict. Notice that the name, color 
and hardness are all kept together, making it easier to see the data relation. This example generates the 
same output as the previous ”C” struct example. 


A$ AAA 
Example 6 
Saving Data in a Nested Dict 
set gems [dict create \ 
Agate [dict create color Brown hardness 7.0] \ 
Amethyst [dict create color Purple hardness 7.0] \ 
Aquamarine [dict create color Blue hardness 7.5] \ 


] 


foreach key [dict keys $gems] { 
puts "$key is colored [dict get $gems $key color] with \ 
[dict get $gems $key hardness] hardness" 


Unlike a “C” struct, the dictionary is a dynamic data structure. More gemstones can be added 
without needing to change the gem array declaration and recompile. You can even add new fields to 
the Tcl dictionary without redefining the data structure. 

The next example adds the family of the gemstone to the dictionary and then displays all the char- 
acteristics and values of all the gems. Notice that using the dict get to extract the keys and values 
for each gemstone makes the output section of the code generic. The code will continue to work when 
fields are added or deleted. 


————o—o—— OO —-n—n—ne—e—e—eeeeeeeeeeeeeeeeeeeeOEe 
Example 7 


dict lappend gems Agate family Quartz 
dict lappend gems Amethyst family Quartz 
dict lappend gems Aquamarine family Beryl] 


foreach key [dict keys $gems] { 
set str "$key" 
foreach {character value} [dict get $gems $key] { 
append str " $character is $value" 


} 
puts “"$str." 
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Script Output 
Agate color is Brown hardness is 7.0 family is Quartz. 
Amethyst color is Purple hardness is 7.0 family is Quartz. 
Aquamarine color is Blue hardness is 7.5 family is Beryl. 


3 USING THE ASSOCIATIVE ARRAY 


Like the keyed list and the dict, the associative array links a data value to a key. The differences are 
that the associative array does not put the data in a given order and the syntax for using an associative 
array is simpler than the dict or keyed list. 

The Tcl associative array can be used just like a C or Fortran array by setting the indices to numeric 
values. If you are familiar with Fortran or Basic programming, you might be familiar with coding 
constructs such as the following. 


C Arrays 
int values[5]; 


char desc[5][80]; 
valuesLO] = 1; 


Tcl Array 


set values(0) 1; 
set desc(0) "First" 


strcpy(descl0], "First"); 


When programming in Tcl, you can link the value and description together more efficiently by 
using a nonnumeric index in the associative array. 


set value("First") 1; 


Data that consist of multiple items that need to be grouped together are frequently collected in 
composite data constructs such as a C struct or a Pascal record. These constructs allow the programmer 
to group related data elements into a single data entity, instead of several entities. The data elements 
within a struct or record can be manipulated individually. 

Grouping information in a struct or record is conceptually a naming convention which the compiler 
enforces for you. When you define the structure, you name the members and define what amount of 
storage space they will require. Once this is done, the algorithm developer generally does not need 
to worry about the internal memory arrangements. The data could be stored anywhere in memory, as 
long as a program can reference it by name. You can group data in an associative array variable by 
using different indices to indicate the different items being stored in that associative array, which is 
conceptually the same as a structure. 


C Structure Tcl Array 


struct { set var(value) 1 
int value; set var(desc) "First" 
char desc[80]; 

} var; 


var.value = 1; 
strcpy(var.desc,"First"); 
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It may not be immediately obvious, but the Tcl variable var groups the description and value 
together just as a struct would do. Another common C data construct is the array of structs. Again, so 
far as your algorithm is concerned, this is primarily a naming convention. By treating the associative 
array index as a list of fields, separated by some obvious character (in the following example, a period 
is used), this functionality is available in Tcl. 


Array of C Structures Tcl Array 

struct { set var(O.value) 1 
int value; set var(0.desc) "First" 
char desc[80]; set var(l.value) 2 

} var[5]; set var(l.desc) "Second" 


var[O].value = 1; 
strcpy(varlLO].desc, "First"); 
var[l].value = 2; 
strcepy(varLl].desc, "Second"); 


You can create naming conventions to group data in Tcl, but the Tcl interpreter does not enforce 
adherence to any naming convention. You can enforce a convention by writing procedures that will 
hide the conventions from people using a package. 


TREES IN TCL 


You do not need to use a binary tree in Tcl for data access speed. The dict and associative array provide 
fast access to data. However, sometimes the underlying data is best represented as a tree. A tree is the 
best way to represent a set of data that subdivides into smaller and smaller subsets. For example, a file 
system is a single large disk divided into directories, which are further divided into subdirectories and 
files. A tree can represent a set of data that has inherent order (with possible branches), such as the 
steps in an algorithm. 

Tcl does not provide a binary tree as a built-in data type; however, the dict data structure can be 
nested to create a tree view of a data set. Since the underlying data structure of a dict is a hash table, 
not an actual tree, there is no need to balance the tree. 

The example below recursively searches a folder and then returns the folder’s contents as a nested 
dictionary. Each folder is a key and the associated value is a dict of the folder’s contents. 


a—___ 
Example 8 
File System as Dict 
proc fileDict {parent} { 
set det {} 
foreach fl [glob —nocomplain $parent/x] { 
if {Lfile type $f1] eq "directory"} { 
dict set det $fl [fileDict $fl] 
} else { 
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dict set det $f1 {} 
} 
} 


return $dct 


To test this, we need a small test folder, which can be created in Linux as shown below. 


=e—_—£§ . <—————-7-i iio 
Example 9 

Create a Set of Folders and Files 

> mkdir /tmp/a 

mkdir /tmp/a/b 

mkdir /tmp/a/c 

echo X > /tmp/a/a.txt 

echo X > /tmp/a/b/ab.txt 

echo X > /tmp/a/c/ac.txt 


VVVVY 


tclsh fileDict.tcl /tmp/a 


Vv 


Script Output 


/tmp/a/a.txt {} /tmp/a/b {/tmp/a/b/ab.txt {}} 
/tmp/a/c {/tmp/a/c/ac.txt {}} 


It’s easier to visualize a tree if it’s printed in a pretty format with indentation to denote the nesting, 
rather than as a raw dictionary. Tcl does not include a pretty-printer for dictionaries, but it’s not difficult 
to create one. 


ooo. an — gy 
Example 10 


A Nested Dict Pretty-Printer 


proc showDict {dct indent} { 
if If dict keys fails, this is not a dictionary. 
d## Print it and return. 
if {[catch {dict keys $dct}]} { 
puts "“[Lstring repeat " " $indent]$dct" 
return 


} 


if Step through the keys in this dictionary and recurse 
foreach k [dict keys $dct] { 
puts "[Lstring repeat " " $indent]$k" 
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set v [dict get $dct $k] 
showDict $v [expr {$indent+2}] 
} 
} 


Using this procedure with the output from the previous test shows the indenting like this: 


Script Output 
/tmp/a/a.txt 
/tmp/a/b 

/tmp/a/b/ab.txt 
/tmp/a/c 
/tmp/a/c/ac.txt 


6.5 TCL AND SQL 


The data structures discussed in this chapter are suitable for organizing temporary data within an appli- 
cation or even for small-to-medium sized data sets saved on a disk. You should use a database engine 
for large or complex persistent data sets. 

Tcl has supported many database engines since version 7 including Oracle, Sybase, Postgres, 
MySQL, ODBC and Sqlite. Each of these databases required a special extension and added a slightly 
different set of new commands for accessing the underlying database. 

Release 8.6 of Tcl includes the tdbc (Tcl DataBase Connection) package which provides a single 
interface to many database engines. 

The dict data structure is very well suited for working with SQL databases and is used with tdbc 
to pass values to and from a database engine. 

The next sections will introduce enough SQL to understand the examples and the Tcl tdbc package. 
If you need to know SQL, there are many books that will provide more details. 

If you are already familiar with SQL, you can skip the next section. 


SQL Basics 


The data in an SQL database is contained in tables. A table can be conceptualized as a spreadsheet. 
Each column along the top is a field like “First Name”, “Last Name’, etc. 

Each row, reading down, is a single element in the table with values for the fields. 

A table of authors might look like this: 


ID First Last 


0) Clif Flynt 
1 Ken Jones 
2 Mark Twain 
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There are several commands in the SQL specification to define and access the tables. The com- 
mands are not case sensitive, but it’s common to capitalize the commands to distinguish them from the 
surrounding data values. 

You define and create a table with the CREATE TABLE command. 


Syntax: CREATE TABLE tableName ( fieldl, field2 ); 
Create and define the fields in a table. 
tableName The name of the table being defined. 
field* A list of the fields and field descriptors. 


The descriptor values must describe the type for the data 
and may define other parameters. The type of data may be 
one of several types including: 


integer integer value 
text string value 


varchar variable length string 


Other parameters may include: 


primary key Marks this field as the primary identifier for a 
row. 

auto_increment Marks this field to be incremented to a new 
value with each insertion. 


not nul] Marks this field to not accept a null value. 


default value Defines the value to place in this field if it is 
otherwise undefined. 


The command below defines and creates an SQL table. This table will hold a collection of authors. 
It has text fields to hold the first and last names, and an integer id that will hold a unique value for each 
record in this table. The AUTO_INCREMENT parameter tells the database engine to automatically assign 
the next higher value whenever new data is inserted into this table. 


CREATE TABLE author ( 
id INTEGER PRIMARY KEY AUTO_INCREMENT , 
First TEXT; 
last TEXT 


Data is added to a table with the INSERT command. 
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Syntax: INSERT INTO tableName (columns) VALUES (values) 
Insert values into selected columns of a table. 
tableName The name of the table to receive the data. 


columns A comma delimited list of columns to 
receive data in the order in which the data 
will be presented. 

values A comma delimited list of values in the 
order defined in the columns field.. 


The next example shows how rows can be added to the author table. Notice the single quotes around 
the names. SQL requires single quotes to define a string. You insert a single quote into a string with a 
pair of single quotes. 


INSERT INTO author (first, last) VALUES (‘Clif’, ‘Flynt’); 
INSERT INTO author (last, first) VALUES (‘Jones’, ‘Ken’); 


Rows are retrieved from a table with the SELECT command. 


Syntax: SELECT fields FROM tableName WHERE test 
Select data in the defined fields one or more 
rows from a table which match a test. 


fields A comma delimited list of the columns to 
select data from. 


tableName Name of the table to select data from. 


test One or more tests to apply to each row to 
determine whether or not to select it. 


The test ina SELECT statement is a boolean expression using the operators shown below. A set 
of tests can be negated with the NOT keyword and multiple tests can be joined with AND or OR. 
columnName = value Contents of a column exactly match a value. 
columnName like value Contents of a column match a wildcard value. 


The wildcard symbol is a % symbol. 


columnName is NULL The data in this column was never defined. 


The next example shows some selections and what they will return using the previously defined 
table and data. 


ee 
Example 11 
Select All Fields, All Rows 

SELECT * FROM author; 


1, Clif, Flynt 
2, Ken, Jones 
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Select Only Last Name, All Rows 
Select last FROM author; 


Flynt 
Jones 


Select First and Last Name Where Last Name Includes the Letter y 
SELECT first, last FROM author WHERE last like ‘%y%’; 


Clif, Flynt 


One feature of relational databases is that a field can point to a record in another table. This means 
that data only has to be in the database once in order to be referenced many times. 
The next example creates a book table that references the authors in the author table. 


ooo —_.—nmnmn wy» 
Example 12 


CREATE TABLE book ( 

id INTEGER PRIMARY KEY AUTO_INCREMENT , 
authorID INTEGER REFERENCES author, 
title TEXT 

ye 


We can populate the book table using the id value from the author table as shown below: 


INSERT INTO book (authorID, title) \ 
VALUES (1, ‘Tcl/Tk: A Developer"s Guide’); 


ee 


Using tdbc 


The tdbc package is included with the 8.6 release of Tcl. It provides a database-engine neutral view 
of SQL databases. The tdbc package supports all the commands that the underlying database engine 
supports with either line-by-line or bulk data returns. 

This section will describe how to use the tdbc package and show how to use the dict commands 
to interact with it. 

The basic program flow for using tdbc looks like this: 


Load tdbc packages. 

Create a new command to interact with a database engine. 
Interact with the database using the new command. 

Close the new SQL command when all interactions are complete. 


PO No 
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There are several ways to interact with the database including single SQL commands, loops, pre- 
compiled SQL commands and variable substitutions. These techniques will be covered working from 
the simple techniques to the more complex. 

In order to use the tdbc package you must first load the packages. Your code must include both 
tdbc and one or more of the tdbc driver packages. The driver packages provide the database neutral 
interface to the database engines. 

The package include commands will look like this: 


it Load the base tdbc package 
package require tdbc 


## Include the sqlite driver 
package require tdbc::sqlite3 


## Include the mysql driver 
package require tdbc::mysql 


Once the packages are loaded, the next step is to create a new command to interact with the 
databases. 


Syntax: tdbc::driver::connection create name -key value 
Create a connection between the Tcl script and the database engine. 


driver The type of database to be connected to. Options 
are sqlite3, mysql, oracle, etc. 

name The name for the new command that is created 
for this connection. 


-key value Keys and values specific to a database engine. 


The code to create a connection resembles the next example. The first line creates a new command 
named sqliteDB that connects to an sqlite3 database named sq]1iteDB.sql. The second command 
creates a new command named mysq10DB that connects to the mySql database testDB as user user 
with a password of password. 


i## Create an sqlite3 database connection. 
tdbc::sqlite3::connection create sqliteDB sqliteDB.sql 


## Create a mySql database connection 


tdbc::mysql::connection create mysqlIDB —db testDB \ 
—user user —password password 


The new database connection command has several subcommands. These subcommands include 
commands to manipulate the data in the tables as well as commands to examine and modify the con- 
nection to the database and to access the database metadata such as the names of tables, foreign keys, 
primary keys and constraints. 


=) 
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These subcommands are supported in tdbc version 1.0. Not all of the introspection commands are 


allrows 


foreach 


prepare 
preparecal | 
statements 


esultsets 


begintransaction 
commit 


rollback 


transaction 


configure 
foreignkeys 


primarykeys 


supported for all database drivers. 


Evaluate an SQL statement and return all rows 
that are selected. 


Evaluate an SQL statement and evaluate a Tcl 
script for each row. 


Prepare an SQL command for future use. 

Prepare a call to a stored procedure. 

Returns a list of statements prepared with 
prepare or preparecall. 

Returns a list of resultsets created by evaluating a 
prepared command. 

Start a transaction. 

Commit (accept) all the updates done during a 
transaction. 

Rollback (discard) any modifications done during 
a transaction. 

A shorthand for collecting a set of Tcl commands 
into a transaction. If the Tcl command set fails, 
the actions are rolled back, else they are 
committed. 

Return or modify the connection options. 

Returns a dictionary with information about a 
table’s foreign keys. 

Returns a dictionary with information about the 
table including the table’s primary key. 


tables Returns a list of the tables that exist in the 
database. 
columns Returns a list of the columns in a table. 
close Close the connection to the database. 
Manipulating Data 


The allrows and foreach subcommands can be used to interact directly with the database. The 
prepare and execute subcommands are used to prepare and delay execution of the SQL statement. 
If your application needs to repeat the same SQL command multiple times, it is better to prepare the 
command and save it until it’s needed. 

The al 1 rows command will evaluate an SQL command. If the command is a SELECT command, 
it will return all the rows that are selected. You can also use the al 1 rows subcommand for commands 
that do not generate any return values. 
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Syntax: dbCmd allrows ?-as format? SQL ?dict? 
Evaluates an SQL command and returns the results in the 
requested format. 
dbCmd The database command created with the 
tdbc::*::create command. 


format The format for the returned data. Options are dict or list. 
SQL An SQL statement to be evaluated. 
dict A dictionary that maps a set of variable names to values. 


The next example creates the author and book tables and then inserts two authors. 


—_——— reson 
Example 13 
Using db Command to Create and Populate Tables 

dbBook allrows { 

CREATE TABLE author ( 
id INTEGER PRIMARY KEY AUTO_INCREMENT, 

first TEXT, 
ast TEXT); 


CREATE TABLE book ( 

id INTEGER PRIMARY KEY AUTO_INCREMENT, 
authorID INTEGER REFERENCES author, 
title TEXT); 


} 


foreach {f 1} {Clif Flynt Ken Jones} { 
dbBook allrows \ 
"INSERT INTO author (first,last) VALUES (‘$f’, ‘$1’)" 


The allrows subcommand will return all results as a set of dictionaries or as a set of lists. The 
default is to return the results as a set of dicts. Each entity returned is a separate dictionary. 

The next example shows the output from using the al 1 rows command to extract the contents of 
the author table as dicts and lists. 


3 -——_ >? S\xXKP$r $NA 
Example 14 
Display Database Returns as Dicts and Lists 
puts "As dicts: [dbBook allrows \ 
{SELECT first, last FROM author}]" 
puts "As lists: [dbBook allrows —as lists \ 
{SELECT first, last FROM author}]" 
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Script Output 


As dicts: {first Clif last Flynt} {first Ken last Jones} 
As lists: {Clif Flynt} {Ken Jones} 


The list format return does not distinguish between empty and NULL. The dict format will return 
an empty value for fields in which there is an empty string but will not include either key or value for 
fields that are not defined. If your application treats an empty field the same as an undefined field, you 
may use the 1 ist format. If your application needs to distinguish between empty contents in a field or 
a NULL (undefined) value in the field, your code must use the dict format. 

The next example shows the differences when a field contains an empty string or is undefined. The 
author Saki had no first name (Saki was a single-name pseudonym), so it is undefined. The dict format 
return has no first key, while the list format return shows an empty string. Mark Twain used first and 
last names, but the first name is defined as an empty string in this example. Both the dict and list return 
show this as an empty string. 
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Example 15 
Empty and Undefined Fields 

dbBook allrows \ 
"INSERT INTO author last VALUES (‘Saki’)" 
dbBook allrows \ 
"INSERT INTO author (first, last) VALUES (*’, ‘Twain’)" 


puts "As Dicts: [dbBook allrows \ 
{SELECT first, last FROM author WHERE last like ‘%a%’;}]" 


puts "As lists: [dbBook allrows —as lists\ 
{SELECT first, last FROM author WHERE last like ‘%a%’;}]" 


Script Output 


As Dicts: {last Saki} {first {} last Twain} 
As lists: {{} Saki} {{} Twain} 


= 

The al] rows command returns all of the results of a search in a single list or dict. This can be 

convenient for small datasets, but may use too many machine resources if the returned dataset is large 

(say, a few terabytes). If the dataset will be large, or if you intend to process each line, it’s better to use 
the foreach subcommand to iterate through the rows. 


Syntax: dbCmd foreach ?-as format? varname SQL ?dict? script 
Evaluates an SQL command and returns the results in the 
requested format. 
dbCmd The database command created with the 
tdbc::*::create command. 
format The format for the returned data. Options are dict or list. 
varName The name of a variable to be hold each row. 
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SQL An SQL statement to be evaluated. 
script A Tel script to be evaluated for each row returned. 


dict A dictionary that maps a set of variable names to values. 


_——_aA_A 
Example 16 
Using the tdbc foreach 
dbBook foreach row {SELECT * FROM author} { 
puts "Dict $row" 


} 
dbBook foreach —as lists row {SELECT * FROM author} { 


puts “List $row" 


Script Output 
Dict id 1 first Clif last Flynt 
Dict id 2 first Ken last Jones 
List 1 Clif Flynt 
List 2 Ken Jones 


.3 Using Referenced Tables 


In order to insert rows into the book table we need to know the author id for the book. The simple (and 
sometimes best) way to do this is to query the database for the relation tables as new rows are inserted, 
as shown in the next example. 


=——_—_—aA_ 
Example 17 
Inserting Rows with References 
foreach {last title} { 
Flynt {Tcl/Tk: A Developer’’s Guide} 
Jones {Practical Programming in Tcl/Tk} } { 
set authorID [dbBook allrows —as lists \ 
"SELECT id FROM author WHERE last=‘$last’"] 
dbBook allrows "INSERT INTO book (authorID, title) \ 
VALUES ($authorID, ‘$title’)" 


The list format return can be used to initialize an associative array. Depending on the size of your 
data set and use frequency it’s often faster to cache values in an associative array rather than hit the 
database for every lookup. This technique is particularly useful when there are many records in one 
table that have references to another smaller table and you need to map the reference to values in the 
referenced table. 
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The next example is similar to the previous one, except that it uses an associative array instead of 
accessing the database for each row to be inserted. The 1 0okup associative array uses the author’s last 
name as the index, and the author 1D value as the array value. This allows the application to map from 
author last name to author ID without a database call. 


$A 
Example 18 
Using an Associative Array to Cache References 
dbBook foreach —as lists xx \ 
"SELECT last,id FROM author" { 
array set lookup $xx 


} 


foreach {last title} { 
Flynt {Tcl/Tk: A Developer’’s Guide} 
Jones {Practical Programming in Tcl/Tk} } { 
dbBook allrows "INSERT INTO book (authorID, title) \ 
VALUES ($lookup($last), ‘$title’)" 


If a statement will be used many times, it is better to use the prepare subcommand to pre-process 
the SQL statement. The prepare subcommand returns the name of a new command that supports 
several subcommands including al ] rows, foreach and execute. 


Syntax: dbCmd prepare SQL 
Prepare an SQL command for future evaluation. 
dbCmd_ The database command created with the 
tdbc::*::create command. 


SQL An SQL statement to be evaluated. This may 
include variables for substitution. 


The all rows and foreach commands are similar to the previously discussed subcommands. The 
main difference is that the connection subcommands require an SQL statement to evaluate while the 
prepared commands have the SQL already embedded. The SQL command can include variables which 
will be substituted when the SQL is evaluated. 


Syntax: dbCmd allrows ?-as format? ?dict? 

Evaluates an SQL command and returns the 

results in the requested format. 

dbCmd The database command created with the 
tdbc::*::create command. 

format The format for the returned data. Options are 
dictor list. 

?dict? An optional dictionary that sets values for 
variables in the SQL command. 
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A variable is defined in the SQL command by starting the variable name with the colon (:) char- 
acter. When the SQL command is evaluated the variables inside the SQL command are substituted. 
The values can be defined by supplying a dictionary of names and values. If no dictionary is supplied 
and there are Tcl variables with the same name as the SQL variables, the value of the Tcl variables is 
substituted into the SQL command. 

The next example demonstrates the prepare command, the prepared command’s execute sub- 
command and variable substitution. These three features are used to populate the author table. A new 
command is created to select values from the author table and the foreach command is used to extract 
lines from that table. 


eee 
Example 19 


package require tdbc 


## Include the sqlite driver 
package require tdbc::sqlite3 


## Create an sqlite3 database connection. 
tdbc::sqlite3::connection create dbBook sqliteDB.sql 


dbBook allrows { 
CREATE TABLE author ( 
id INTEGER PRIMARY KEY AUTO_INCREMENT, 
first TEXT, 
last TEXT); 


} 


i## Prepare a command for inserting into author table 

set authorInsert [dbBook prepare { 
INSERT INTO author (first, last) VALUES (:first, :last); 
} ] 


foreach first {Clif Ken Mark} last {Flynt Jones Twain} { 
$authorInsert execute 


} 


i## Prepare a command to select rows from the author table 
## pattern is defined in a dict. 
set authorSearch [dbBook prepare { 
SELECT * from author WHERE last like :pattern; 
} J 


$authorSearch foreach rowDict {pattern %n%} { 
puts “rowDict: $rowDict" 


} 
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Script Output 


rowDict: id 1 first Clif last Flynt 
rowDict: id 2 first Ken last Jones 
rowDict: id 3 first Mark last Twain 


Introspection into Databases 
The tdbc package provides tools to examine a database’s meta-data as well as the data in the tables. 
The introspection commands include the configure, foreignkeys, primarykeys, tables and 
columns. 

The configure command provides access to database connection options. Database engines sup- 
port different sets of configuration options. The configure command returns a dictionary that lists 
the supported options and their values. 


Syntax: dbCmd configure ?-parameter? ?value? 
Returns or modifies configurable options for a database connection. 


dbCmd A database connection command defined with 
tdbc::driver connection 


-parameter Aconfigurable option for this database. If no -parameter is 
provided, a dictionary of all appropriate configurable 
parameters and their values is returned. If an -parameter 
is provided, but no value, the value for just this parameter is 
returned. If both -parameter and value are provided, the 
value for this parameter is modified. 


value The new value for this parameter. 


This example shows the return value for connections to an SQLite database and a MySq] database. 
SQLite is a single connection database, so it does not need a user and password to define a connection. 
MySql supports multiple connections, and thus needs a user and password to create a connection. These 
differences (and others) are shown in the configure output. 
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Example 20 


Configure Options 


i## Create an sqlite3 database connection. 
tdbc::sqlite3::connection create sqliteDB sqliteDB.sql 


i## Create a mySql database connection 


tdbc::mysql::connection create mysqIDB —db testDB \ 
—user user —password password 


if Report the sqlite options 
puts "SQLite: [sqliteDB configure]" 
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i## Report the mysql options 
puts "MySql: LmysqlDB configure]" 


Script Output 


SQLite: —encoding utf—8 —isolation serializable 
—readonly 0 —timeout 0 


MySql: -—compress 0 —database testDB —encoding utf-—8 
—host localhost —interactive 0 —isolation repeatableread 
—password {} —port 3306 —readonly 0 
—socket /var/run/mysqld/mysqld.sock —ssl_ca {} 
—ssl_capath {} -ssl_cert {} -—ssl_cipher {} —ssl_key {} 
—timeout 28800 —user user@localhost 


The tables and columns provide introspection into the database schema. The values returned 
by these commands vary depending on the underlying database program and the Tcl driver. If your 
application needs to be able to examine the database it’s connected to (for instance, to generate input 
forms automatically), you will need to check the exact return values for the database and drivers you 
are using. 


Syntax: dbCmd tables ?pattern? 
Returns a dictionary providing information about one or more 
tables. 
dbCmd A database connection command defined with 
tdbc::driver connection 
pattern A pattern to select which table’s information will 
be returned. If no pattern, all tables are selected. 


The next example shows the returns for SQLite and MySql databases using the author and book 
tables that we’ ve defined in previous examples. 


eee 
Example 21 


Tables 


i## Create an sqlite3 database connection. 
tdbc::sqlite3::connection create sqliteDB sqliteDB.sql 


## Create a mySql database connection 


tdbc::mysql::connection create mysqIDB —db testDB \ 
—user user —password password 


puts "SQLite Tables: [sqliteDB tables]" 
puts "MySql Tables: [mysqlDB tables]" 
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Script Output 
SQLite Tables: 
author {type table name author tbl_name author rootpage 2 
sql {CREATE TABLE author ( 
id INTEGER PRIMARY KEY AUTO_INCREMENT, 
first TEXT, 
last TEXT) 


} 
book {type table name book tbl_name book rootpage 3 
sql {CREATE TABLE book ( 
id INTEGER PRIMARY KEY AUTO_INCREMENT, 
authorID INTEGER REFERENCES AUTHOR, 
title TEXT) 


} 


MySql Tables: author {} book {} = 


The tables command returns information about one or more tables. The columns command 
returns internal data about the columns in a specific table. 


Syntax: dbCmd columns table ?pattern? 
Returns a dictionary providing information about one or more 
fields in a table. The return is a nested dictionary in which the 
key is the name of a field and the value is another dictionary of 
parameters and values. 


dbCmd A database connection command defined with 
tdbc::driver connection 
table The table to return column information for. 


pattern A pattern to select which column’s information will be 
returned. If no pattern, all columns in the table are 
selected. 


———————— eee eee 
Example 22 


Columns 
puts "SQLite: \n£sqliteDB columns author]" 


puts "MySql: \nLmysqlDB columns author ]" 


Script Output 
SQLite: 
id {cid 0 name id type integer notnull 0 pk 1 precision 0 
scale 0 nullable 1} 


6.5 TclandSQL 173 


first {cid 1 name first type text notnull 0 pk 0 precision 
0 scale 0 nullable 1} 

last {cid 2 name last type text notnull 0 pk 0 
precision 0 scale 0 nullable 1} 


MySql: 

id {name id type integer precision 11 scale 0 
nullable 0} 

first {name first type text precision 65535 scale 0 
nullable 1} 

last {name last type text precision 65535 scale 0 
nullable 1} 


The primarykeys and foreignkeys return information about the primary keys and foreign keys 
(references) in one or more tables. These commands return a dictionary that describes the parameters 
and values that the underlying database and driver support. 

The example below shows the return from the primarykeys command when sent to a MySql 
connection with two databases that contain a table named author. 


a 
Example 23 
Columns Use 

puts LmysqlDB primarykeys author] 


Script Output 
{tableSchema Library1 tableName author 
constraintSchema Libraryl constraintName PRIMARY 
columnName id ordinalPosition 1} 
{tableSchema testDB tableName author 
constraintSchema testDB constraintName PRIMARY 
columnName id ordinalPosition 1} 


The primarykeys, tables and columns subcommands can be used to make a single generic 
entry procedure for databases. The next example shows a generic prompt/response type interaction to 
query a user for fields and data to enter. 

If the AUTO_INCREMENT parameter is set, the value of the primary key is set by the database engine, 
rather than being defined in the INSERT command. This example uses the primarykeys command to 
determine the primary key and only query for input on the non-primary key fields. 

When a user provides a value, the name of the field and the new value are appended to lists to 
be inserted into the SQL command and values are set in the dictionary to be passed to the all rows 
command. 
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a MN TTT 
Example 24 


JHAABAABA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA 
i# proc promptResponse {dbCmd table}—— 

dt Query a user for values to insert into a table 

if Arguments 
if dbCmd — A command as returned from a tdbc::connection call 
if table — The name of the table to recieve a new row 


df 

if Results 

if The database is modified by having a new row inserted. 
fl 


proc promptResponse {dbCmd table} { 


i## Find the primary key for this table 
foreach d [$dbCmd primarykeys $table] { 
## If this dictionary references the requested table, 
if get the name of the primary key field. 
if {!Cdict exists $d tableName] || 
[dict get $d tableName] eq $table)} { 
set primary [string tolower [dict get $d columnName]] 


} 


} 


if Step through the filed names and dictionaries 
if returned by the columns command. 


foreach {field dct} [$dbCmd columns $table] { 
## If this field is not the primary key 
## query the user for a value 


if {[string tolower $field] ne $primary} { 


## extract the type and name from the dictionary 
set type [dict get $dct type] 
set name [dict get $dct name] 


dt Query the user and accept the user input 
puts —nonewline "$field ($type): " 

set input [gets stdin] 

flush stdout 


if {$input ne ""} { 
## Append the name of this field list of fields 
lappend fields "$name" 


i## Append the name to a list of variables 
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lappend vars ":$name" 


if set a dictionary key/value pair 
## to map field name to a value 
dict set data $name $input 
} 
} 
} 


i Join the lists into strings for the SQL command. 
set fields [join $fields ,] 
set vars [join $vars ,] 


i Show the command that will be invoked to INSERT 
# data into the table. 


puts "Insert Command is:" 
puts "$dbCmd allrows {INSERT INTO $table ($fields) " 
puts " VALUES ($vars)} {$data}" 


i Insert the data into the database. 
$dbCmd allrows "INSERT INTO $table ($fields) VALUES ($vars)" $data 


Script Output 
first (text): Clif 
last (text): Flynt 
Insert Command is: 
mysqlDB allrows {INSERT INTO author (first,last) 
VALUES (:first,:last)} {first Clif last Flynt} 


6.6 PERFORMANCE 


So, how do lists, dicts and associative arrays compare when it comes to accessing a particular piece of 
data? The following example shows the results of plotting the list, dict and array access times. 

Note that the time to access the last element in a list increases linearly with the length of the 
list. In Tcl 8.3, the list-handling code was rewritten to improve the performance, but even with that 
performance improvement the access speed for dict and array elements is much faster and does not 
degrade as the number of elements increases. 

Note that the performance between | search and an array access is not significantly different until 
you exceed 100 elements in the list. If your lists are shorter than 100 elements, you can use whichever 
data construct fits your data best. 
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The next examples show the code that was used to generate the accompanying graph. The Tcl time 
command returns clock time (not CPU time) that it takes a command to run. This can be influenced by 
other background tasks that might interrupt the Tcl interpreter and extend the clock time. Background 
tasks may make a set of code take longer, but will never make code run faster. This is the reason for 
running the test multiple times and taking the minimum time. 


SE 
Example 25 
List Element Access Time 
for {set i 0} {$i < 500} {incr ji} { 
set x "abcd. $i.efg" 
lappend Ist $x 
set min [lindex [time {lsearch $lst $x} 100] 0] 
for {set j 0} {$j < 10} {incr j} { 
set tmp [Llindex [time {lsearch $lst $x} 100] 0] 
if {$tmp < $min} {set min $tmp} 
} 


puts "$i $min" 


Array Element Access Time 


for {set i 0} {$i < 500} {incr ji} { 
set x "abcd. $i.efg" 
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set arr($i) $x 
set min Llindex [time {set y $arr($i)} 100] 0] 
for {set j 0} {$j < 10} {incr j} { 
set tmp [Llindex [time {set y $arr($i)} 100] 0] 
if {$tmp < $min} {set min $tmp} 
} 


puts "$i $min" 


Dict Element Access Time 
for {set i O} {$i < 500} {incr i} { 

set x "abcd.$i.efg" 

dict set dct $i $x 

set min Llindex [time {dict get $dct $i} 100] 0] 

for {set j 0} {$j < 10} {incr j} { 
set tmp [Llindex [time {dict get $dct $7} 100] 0] 
if {$tmp < $min} {set min $tmp} 


puts "$i $min" 


Note that although accessing a known index in an associative array is very fast, using the array 
names command builds a list of array indices, and extracts the list of names that match a pattern. 
This operation becomes slower as the number of indices increases. If you need to deal with applications 
that have thousands of nodes, it may be better to use multiple arrays rather than indices with multiple 
fields. 


6.7 BOTTOM LINE 


This chapter has demonstrated several ways to use Tcl lists, dicts and associative arrays with data read 
from a file, in-memory data and data from an SQL database. 


e Lists can be used to organize information as position-oriented data or as key/value pairs. 

e Dicts organize data as ordered key/value pairs. 

e Indices in an array and keys in a dict must be unique. 

e Dicts can be nested to manipulate tree structured data. 

e Naming conventions can be used with associative array indices to provide the same functionality 
as structures and arrays of structures. 

e A variable can contain the name of another variable, providing the functionality of a pointer. 

e The catch command is used to catch an error condition without causing a script to abort 
processing. 
Syntax: catch script ?varName? 
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e The file command provides access to the file system. 
Syntax: file type pathName 


Syntax: file nativename pathName 
Syntax: file delete pathName 
Syntax: file exists pathName 
Syntax: file isdirectory pathName 


Syntax: file isfile pathName 
e The glob command returns directory entries that match a particular pattern. 
Syntax: glob ?-nocomplain? ?--? pattern ?pattern? 
e The lreplace command replaces one or more list elements with 0 or more new elements. 


Syntax: lreplace list first last ?element element ...? 
e The join command will convert a list into a string, using an optional character as the element 
separator. 


Syntax: join ?joinString? 
e Accessing an array element is frequently faster than using | search to find a list element. 


6.8 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under 
a minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e 100 Given a large amount of data, which is likely to be faster: using 1 search to search a list or 
indexing the data in an associative array? 


¢ 101 What Tcl command would convert a Tcl list into a string with commas between the list 
elements? 


e 102 What associative array indices would provide a data relationship similar to the following? 
struct { 
char xtitle; 
char *author; 
float price; 
} books[3]; 
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e 103 What will be the first Tcl command in the error stack generated by the Tcl command error 
"Tllegal value"? 


e 104 The code fragment set result [expr $numerator/ $divisor] will fail if the 
numerator or divisor is an illegal value. Write a code fragment to divide one value by another 
without generating an error. If the numerator or divisor is an illegal value, set result to the 
phrase Not-A-Number. 


e 105 What Tcl command will report the type of file (a normal file or directory, for example) given a 
file name? 


e 200 Given a set of data in which each line follows the form Name: UserName: Password, write a 
foreach command that will split a line into the variables name, user, and passwd. 


e 201 Given the following 
{ 
{ {Name {John Doe}} {UserName johnd} {Password JohnPwd} } 
{ {UserName jdoe} {Name {Jane Doe}} {Password JanePwd} } 
{ {Name {John Smith}} {Password JohnPwd} {UserName johns} } 
{ {UserName jonnjonzz} {Password manhunter} {Name {John Jones}} } 
} 
a. What combination of 1search and 1 index commands would find the password for John 
Jones? 
b. Write a short script that will list users with identical passwords. 
c. Will you get the record with John Doe’s password using an | search pattern of John? 
d. Write a short script that would change John Smith’s user name to jsmith. 


¢ 300 The kitchen in an automated restaurant might receive orders as patrons select items from a 
menu via a format such as the following. 
{{Table 2} {burger} {ketchup mustard}} 
{{Table 3} {drink} {medium}} 
{{Table 2} {fries} {large}} 
{{Table 1} {BLT} {no mayo}} 
{{Table 3} {Complete} {} } 
{{Table 1} {drink} {smal1}} 
{{Table 1} {Complete} {} } 
Write a script that will accept data in a format such as this, collecting the items ordered at a table 
and reporting a table’s order when the Comp] ete message is received. After reporting an order, it 
should be ready to start assembling a new order for that table. 


e 301 Write a script that will accept multiple lines in the form “author, title”, and will create a list 
author, title, author, title. .. 
Clif Flynt, Tcl/Tk: A Developer’s Guide 
Richard Stevens, TCP/IP Illustrated 
Donald Knuth, The Art of Computer Programming: Vol 1 
Donald Knuth, The Art of Computer Programming: Vol 2 
Donald Knuth, The Art of Computer Programming: Vol 3 
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John Ousterhout, Tcl and the Tk Toolkit 
Richard Stevens, Unix Network Programming 
Convert the list to an associative array that would allow you to get lists of books by an author. 


e¢ 302 Write a “Safe Math” procedure that will accept a mathematical expression, and evaluate it and 
return the result without generating an error. If any of the values in the math expression are illegal, 
return the phrase “Illegal Expression” instead of a numeric answer. 


CHAPTER 


Procedure Techniques 


One key to writing modular code is dividing large programs into smaller subroutines. Tcl supports the 
common programming concept of subroutines—procedures that accept a given number of arguments 
and return one or more values. Tcl also supports procedures with variable numbers of arguments, and 
procedures with arguments that have default values. 

The Tcl interpreter allows scripts to rename procedures and create new procedures while the script 
is running. When a new procedure is created by another procedure, the new procedure is defined in the 
global scope and is not deleted when the procedure that created it returns. 

Previous chapters introduced some of these capabilities. This chapter expands on that discussion 
with more details and examples, including the following. 


e Defining the arguments to procedures 

e Renaming and deleting procedures 

e Examining a procedure’s body and arguments 

e Performing Tcl variable and command substitutions on a string 
e Constructing and evaluating command lines within a script 

e Turning a set of procedures and data into an object 


7.1 ARGUMENTS TO PROCEDURES 


When the proc command is invoked to create a new procedure, the new procedure is defined with a 
name, a list of arguments, and a body to evaluate when the procedure is invoked. When a procedure 
is called, the Tcl interpreter counts the arguments to confirm that there are as many arguments in the 
procedure call as there were in the procedure definition. If a procedure is called with too few arguments, 
the Tcl interpreter generates an error message resembling this: 


no value given for parameter "argl" to "myProcedure" 


If a procedure is called with too many arguments, the Tcl interpreter generates an error message 
resembling this: 


called "myProc" with too many arguments 


This runtime checking helps you avoid the silent errors that occur when you modify a procedure 
to take a new argument and miss changing one of the procedure calls. However, there are times when 
you do not know the number of arguments (as with the expr command) or want an argument to be 
optional, with a default value when the argument is not present (as | is the default increment value for 


Tel/Tk: A Developer’s Guide. DOI: 10.1016/B978-0-12-384717-1.00007-5 1 8 1 
© 2012 Elsevier, Inc. All rights reserved. 
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the incr command). You can easily define a procedure to handle a variable number of arguments or 
define a default value for an argument in Tcl. 


7.1.1 Variable Number of Arguments to a Procedure 


You can define a procedure that takes a variable number of arguments by making the final argument in 
the argument list the word args. When this procedure is called with more arguments than expected, 
the Tcl interpreter will concatenate the arguments that were not assigned to declared variables into a 
list and assign that list to the variable args, instead of generating a too many arguments error. 

Note that args must be the last argument in the argument list to get the excess arguments assigned 
to it. If there are other arguments after the args argument, args is treated as a normal argument. 
In the following example, the procedure showArgs requires at least one argument. If there are more 
arguments, they will be placed in the variable args. 


se .. 
Example 1 


Script Example 


i## A proc that accepts a variable number of args 
proc showArgs {first args} { 
puts “first: $first" 
puts "args: $args" 
} 
## Example Script 
puts "Called showArgs with one arg" 
showArgs oneArgument 
puts "\nCalled showArgs with two args" 
showArgs oneArgument twoArgument 
puts "\nCalled showArgs with three args" 
showArgs oneArgument twoArgument threeArgument 


Script Output 
Called showArgs with one arg 
first: oneArgument 
args: 


Called showArgs with two args 
first: oneArgument 
args: twoArgument 


Called showArgs with three args 
first: oneArgument 
args: twoArgument threeArgument 


| 
7.1.2 Default Values for Procedure Arguments 


The technique for setting a default value for an argument is to define the argument as a list; the first 
element is the argument name, and the second is the default value. When the arguments are defined 
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as a list and a procedure is called with too few arguments, the Tcl interpreter will substitute the 
default value for the missing arguments, instead of generating ano value given for parameter 
error. 


Oooo —_””——nnnkn—n— wg _ = 
Example 2 


Script Example 


i## A proc that expects at least one arg, and has defaults for 2 
proc showDefaults {argl {numberArg 0} {stringArg {default val}}} { 
puts “argl: $argl" 
puts "numberArg: $numberArg" 
puts "stringArg: $stringArg" 
} 


## Example Script 

puts "\nCalled showDefaults with one argument" 
showDefaults firstArgument 

puts "\nCalled showDefaults with two arguments" 
showDefaults firstArgument 3 

puts "\nCalled showDefaults with three arguments" 
showDefaults firstArgument 3 "testing" 


Script Output 
Called showDefaults with one argument 
argl: firstArgument 
numberArg: 0 
stringArg: default val 


Called showDefaults with two arguments 

argl: firstArgument 

numberArg: 3 

stringArg: default val 

cback nCalled showDefaults with three arguments 
argl: firstArgument 

numberArg: 3 

stringArg: testing 


The procedure showDefaults must be called with at least one argument. If only one argument is 
supplied, numberArg will be defined as 0, and stringArg will be defined as default val. 

Note that the order of the arguments when a procedure is invoked must be the same as the 
order when the procedure was defined. The Tcl interpreter will assign the values in the order in 
which the variable names appear in the procedure definition. For example, you cannot call procedure 
showDefaults with arguments for arg] and stringArg, but must use the default for number - 
Arg. The second value in the procedure call is assigned to the second variable in the procedure 
definition. 
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You cannot create a procedure that has an argument with a default before an argument without a 
default. If you created a procedure such as the following, 


proc badProc {{argWithDefault dflt} argWithOutDefault} {...} 


and called it with a single argument, it would be impossible for the Tcl interpreter to guess for which 
variable that argument was intended. Tcl would assign the value to the first variable in the argument 
list, and the error return would resemble the following. 


% badProc aa 
no value given for parameter "argWithOutDefault" to "badProc” 


7.2 RENAMING OR DELETING COMMANDS 


The proc command will create a new procedure. Sometimes you may also need to rename or delete a 
procedure. For example, if you need to use two sets of Tcl code that both have a processData pro- 
cedure, you can load one package, rename the processData procedure to packagelprocessData, 
and then load the second package. (A better solution is to use a name space, as described in Chapter 8.) 

If you have had to deal with name collisions in libraries and DLLs before, you will appreciate this 
ability. 

The rename command lets you change the name of a command or procedure. You can delete a 
procedure by renaming it to an empty string. 


Syntax: rename oldName ?newName? 
Rename a procedure. 
oldName The current name of the procedure. 


?newName? The new name for the procedure. If this is an empty string, 
the procedure is deleted. 


The following example shows the procedure a1 pha renamed to beta and then deleted. 


—_——— eho 
Example 3 


Script Example 


proc alpha {} { 

return "This is the alpha proc" 
} 
## Example Script 
puts "Invocation of procedure alpha: [Lalpha]" 
rename alpha beta 
catch alpha rtn 
puts "Invocation of alpha after rename: $rtn" 
puts "Invocation of procedure beta: [beta]" 
rename beta "" 
beta 
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Script Output 
Invocation of procedure alpha: This is the alpha proc 
Invocation of alpha after rename: invalid command name "alpha" 
Invocation of procedure beta: This is the alpha proc 
invalid command name "beta" 


7.3 GETTING INFORMATION ABOUT PROCEDURES 


The Tcl interpreter is a very introspective interpreter. A script can get information about most aspects 
of the interpreter while the script is running. The info command that was introduced in Chapter 6 
provides information about the interpreter. These four info subcommands will return the names of all 
commands known to the Tcl interpreter, and can return more information about procedures that have 
been defined by Tcl scripts using the proc command. 


info commands pattern Returna list of commands with names that match a pattern. This includes 
both Tcl procedures and commands defined by compiled C code. 

info procs pattern Return a list of procedures with names that match a pattern. This will 
return only the names of procedures defined with a proc command, not 
those defined using compiled C code. 


info body procName Return the body of a procedure. This is only valid for Tcl commands 
defined as a proc. 
info args procName Return the arguments of a procedure. This is only valid for Tcl commands 


defined as a proc. 


The proc subcommand will list the available procedures in an interpreter. This includes many of 
the Tcl and Tk built-in commands that are implemented as Tcl scripts, but not the commands that are 
implemented in “C” code. 

The commands subcommand will list the available commands that match a glob pattern. This 
includes both procedures and commands implemented in “C” code. This can be used to confirm that 
an expected set of code has been loaded. 


Syntax: info procs pattern 


Syntax: info commands pattern 
Returns a list of command or procedure names that match the pattern. If no command 
names match the pattern, an empty string is returned. 
pattern A glob pattern to attempt to match. 


—————— eee eee 
Example 4 


if Check to see if md5 command is defined. If not, load a 
if Tcl version 
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if {{string match Linfo commands md5] ""J} { 
source "md5.tcl" 


} 
mm 


The info body command will return the body of a procedure. This can be used to generate and 
modify procedures at runtime or for distributed applications to exchange procedures. 
Syntax: info body pattern 
Returns the body of a procedure. 
procName The procedure from which the body will be returned. 


—————————————————————— inn eee SSS 
Example 5 


Script Example 


proc example {one two} { 
puts "This is example" 


} 
## Display the body of the proc 
puts "The example procedure body is:\n Linfo body example]" 


Script Output 


The example procedure body is: 
puts "This is example" 


The info args command returns the argument list of a procedure. This is useful when debugging 
code that has generated its own procedures. 


Syntax: info args procName 
Returns a procedure’s argument list. 
procName The procedure from which the arguments will be returned. 


—_—_—_—_—_—_—_—_—_——:.:?(. ooo 
Example 6 


Script Example 


puts "The example proc has [llength Linfo args example]] arguments" 


Script Output 


The example proc has 2 arguments 


The next example shows how you can check that a procedure exists and create a slightly different 
procedure from it. 
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EE _________________ 
Example 7 
Script Example 
## Define a simple procedure. 
proc alpha {args} { 
puts "proc alpha is called with these arguments: $args" 


} 


# Confirm that the procedure exists 
if {Linfo commands alpha] != ""} { 
puts "There is a procedure named alpha" 


} 


# Get the argument list and body from the alpha procedure 
set alphaArgs Linfo args alpha] 
set alphaBody Linfo body alpha] 


i## Change the word "alpha" in the procedure body to "beta" 
regsub "alpha" $alphaBody "beta" betaBody 


i## Create a new procedure "beta" that will display its arguments. 
proc beta $alphaArgs $betaBody 


## Run the two procedures to show their behavior 
alpha How about 
beta them Cubs. 


Script Output 
There is a procedure named alpha 
proc alpha is called with these arguments: How about 
proc beta is called with these arguments: them Cubs. 


| SUBSTITUTION AND EVALUATION OF STRINGS 


Section 3.2 discussed how the Tcl interpreter evaluates a script: the interpreter examines a line, per- 
forms a pass of command and variable substitutions, and then evaluates the resulting line. A Tcl script 
can access these interpreter functions to perform substitutions on a string or even evaluate a string as a 
command. This is one of the unusual strengths in Tcl programming. Most interpreters do not provide 
access to their parsing and evaluation sections to the program being interpreted. The two commands 
that provide access to the interpreter are subst and eval. 


Performing Variable Substitution on a String 


The set command returns the current value of a variable as well as assigning a value. A common use 
for this is to assign and test a variable in one pass, as shown in the following. 
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while {Lset len [string length $password]] < 8} { 
puts "$len is not long enough. Use 8 letters" 
set password [gets stdin] 


} 


This capability is also useful when you have a variable that contains the name of another variable, 
and you need the value from the second variable, as shown in the following. 


~ set al 

% set ba 

% puts "The value of $b is [set $b]" 
The value of a is 1 


If you need to perform more complex substitutions, you can use the subst command. The subst 
command performs a single pass of variable and command substitutions on a string and returns the 
modified string. This is the first phase of a command being evaluated, but the actual evaluation of the 
command does not happen. If the string includes a square-bracketed command, the command within 
the brackets will be evaluated as part of this substitution. 


Syntax: subst string 
Perform a substitution pass upon a string. Do not evaluate the results. 
string The string upon which to perform substitutions. 


The subst command can be used when you need to replace a variable with its content but do not 
want to evaluate it as a command. The previous example could be written as follows, using subst. 


2 set al 

% set ba 

% puts [subst "The value of $b is $$b"] 
The value of a is 1 


In this example, the $$b is replaced by $a in the usual round of substitutions, and then $a is replaced 
by | by the subst command. In this case, you can obtain the same result with either set or subst. 
As the string becomes more complex, the subst command becomes a better option, particularly when 
combined with the eval command, as discussed in the following section. 


7.4.2 Evaluating a String as a Tcl Command 


The eval command concatenates its arguments into a string and then evaluates that string as if it were 
text in a script file. The eval command allows a script to create its own command lines and evaluate 
them. 

You can use eval to write data-driven programs that effectively write themselves based on the 
available data. You can also use the eval command to write agent-style programs, where a task on one 
machine sends a program to a task on another machine to execute. These techniques (and the security 
considerations) are described in later chapters. 


Syntax: eval arg ?args? 
Evaluate the arguments as a Tcl script. 


arg ?args? These arguments will be concatenated into 
a command line and evaluated. 
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Example 8 


Script Example 


set cmd(0) {set a l} 
set cmd(1) {puts "start value of A is: $a"} 
set cmd(2) {incr a 3} 


set cmd(3) {puts "end value of A is: $a"} 
for {set i O} {$i < 4} {incr ji} { 

eval $cmd($i) 
} 


Script Output 


start value of A is: 1 
end value of A is: 4 


Because the arguments to eval are concatenated, the command that is evaluated will lose one level 
of grouping. Discarding a level of grouping is a common use of the eval command. 

The next example demonstrates some of the tricks involved in removing the grouping for some 
sections of a command while maintaining the grouping in others. 

In Tcl 8.5, a new operator was added to Tcl to remove the grouping. The three character {*} operator 
is much simpler to use than collections of extra lists and eval commands, as shown in the last of these 
examples. One advantage of the {*} operator over eva is that it allows selection of individual variables 
to be expanded, while the eval command expands all the variables, which may require adding layers 
of grouping to some variables. 

For example, in the next example, the regexpArgs variable has three options for the regexp 
command. If this command is invoked as regexp $regexpArgs, the three options are presented to 
the regexp command as a single argument, and the regexp command generates an error, since it does 
not supporta "-line -nocase --",-option. 

The eval command can be used to separate the list of options into three separate options, as the 
regexp command requires. However, we do not want to separate the string the regular expression is 
being compared to into separate words. When using eval to split one set arguments you must also add 
a layer of grouping to elements you do not want to split. 


e The following generates a runtime error. 
set regexpArgs {-line -nocase --} 
set str "This is a test" 
set exp {is.*} 
regexp $regexpArgs $exp $str ml 
it After Substitution 
## regexp {-line -nocase --} {is.*} {This is a test} ml 


e The following is legal, but the string is also split into separate arguments. 


eval regexp $regexpArgs $exp $str ml 
it After Substitution: 
it regexp -line -nocase -- is.* This is a test ml 


190 CHAPTER 7 Procedure Techniques 


e The following is legal code, which works as expected. 
eval regexp $regexpArgs $exp {$str} ml 
it After Substitution: 
if regexp -line -nocase -- is.* {This is a test} ml 


e The following is legal code, which works as expected and is preferred style using eval. 


eval regexp $regexpArgs $exp [list $str] ml 
if After Substitution: 
if regexp -line -nocase -- is.* {This is a test} ml 


e The following is legal code, which works as expected. This is the preferred style for Tcl 8.5 and 
newer. 
regexp {*}$regexpArgs $exp $str ml 
if After Expansion: 
if regexp -line -nocase -- is.* {This is a test} ml 


————————EEEE——————————_ SSS SSS 
Example 9 
Script Example 

set regexpArgs {—line —nocase ——} 

set str "This is a test" 

set exp {iS.x} 

set ml "" 

set fail [catch {regexp $regexpArgs $exp $str ml} message] 

if {$fail} { 

puts “regexp failed: $message" 

} 

set rtn [regexp {*}$regexpArgs $exp $str ml] 

puts "Second regexp returns: $rtn" 

puts "Matched: $m1" 


Script Output 
regexp failed: bad switch "-line -nocase --": must be -all, 
-about, -indices, -inline, -expanded, -line, -linestop, 
-lineanchor, -nocase, -start, or -- 
Second regexp returns: 1 
Matched: is is a test 


7.5 WORKING WITH GLOBAL AND LOCAL SCOPES 


The Tcl variable scope rules provide a single global scope, and private local scopes for each proce- 
dure being evaluated. This facility makes it easy to write robust, modular programs. However, some 
applications require scripts being evaluated in one local scope to have access to another scope. The 
upvar and uplevel commands allow procedures to interact with higher-level scopes. 
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This section discusses scopes and the upvar and uplevel commands in more detail than previ- 
ously, and shows how to use the up| evel and upvar commands. This discussion is expanded upon 
in Chapter 8, which discusses the namespace command. For now, a namespace is a technique for 
encapsulating procedures and variables in a named, private scope. 


76 


7.5.1 Global and Local Scope 


The global scope is the primary scope in a Tcl script. All Tcl commands and procedures that are not 
defined within a namespace are maintained in this scope. All namespaces and procedures can access 
commands and variables maintained in the global scope. 

When a procedure is evaluated, it creates a local scope. Variables are created in this scope as neces- 
sary, and are destroyed when the procedure returns. The variables used within a procedure are visible 
to other procedures called from that procedure, but not to procedures outside the current call stack. 

Any variable defined outside of the procedures or identified with the g]o0bal command is main- 
tained in the global scope. Variables maintained in the global scope persist until either the script exits 
or they are explicitly destroyed with the unset command. 

These variables can be accessed from any other scope by declaring the variable to exist in the 
global scope with the global command. Note that the global command must be evaluated before 
that variable name is used in the local scope. The Tcl interpreter will generate an error if you try to 
declare a variable to be global after using it in a local scope. 


S) 


set globalVar "I’m global" 
proc goodProc {} { 
global globalVar 
i## The next line prints out 
# "The globalVar contains: I’m global" 
puts "The globalVar contains: $globalVar" 
} 
proc badProc {} { 
set globalVar "This defines ‘globalVar’ in the local scope" 
if The next line causes an error 
global globalVar 


} 


Each time a procedure invokes another procedure, another local scope is created. These nested 
procedure calls can be viewed as a stack, with the global scope at the top and each successive procedure 
call stacked below the previous ones. 

A procedure can access variables within the global scope or within the scope of the procedures that 
invoked it via the upvar and up]evel commands. The upvar command will link a local variable to 
one in a previous (higher) stack scope. 


Syntax: upvar ?/evel? varNamel localNamel ?Name2? ?localName2? 


——— Cen 
Example 10 


Script Example 


proc top {topArg} { 
set localArg Lexpr $topArgt1] 
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puts "Before calling bottom localArg is: $localArg" 

bottom localArg 

puts "After calling bottom, localArg is: $localArg" 
} 


proc bottom {bottomArg} { 
upvar $bottomArg arg 
puts "bottom is passed $bottomArg with a value of $arg" 
incr arg 


} 


top 2 


Script Output 


Before calling bottom localArg is: 3 
bottom is passed localArg with a value of 3 
After calling bottom, localArg is: 4 


The up| evel command will concatenate its arguments and evaluate the resulting command line in 
a higher level scope. The uplevel is like eval, except that it evaluates the command in a different 
scope instead of the current scope. 

The main use for the up]evel command is to implement program flow control structures such 
as for, while, and if. Using the uplevel command as a macro facility to change variables in 
a calling scope (as done in the next example) is a bad idea that leads to hard-coded variable names 
and code that is difficult to maintain. When you need to modify a variable that does not exist in 
the current scope, you should pass the variable name and use upvar in your procedure rather than 
uplevel. 

The following example shows a set of procedures (Stackl, stack2, and stack3) that call each 
other and then access and modify variables in the scope of the procedures that called them. All of these 
stack procedures have a local variable named x. Each is a separate variable. Note that procedure 
stack1 cannot access the variables in the scope of procedure stack2, although stack2 can access 
variables in the scope of stack1. 


—_——— eee 
Example 11 


Script Example 


i## Create procedure stackl with a local variable x. 
i## =©6display the value of x, call stack2, and redisplay the 
i## =©6value of x 


proc stackl {} { 
set x 1; 
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puts "X in stackl starts as $x 
stack2 
puts "X in stackl ends as $x" 
putse" 

} 


# Create procedure stack2 with a local variable x. 
# =©6display the value of x, call stack3, and redisplay the 
# =value of x 


proc stack2 {} { 
set x 2; 
puts "X in stack2 starts as $x" 
stack3 
puts "X in stack2 ends as $x 


i## Create procedure stack3 with a local variable x. 
i## display the value of x, 
i## display the value of x in the scope of procedures that 
if invoked stack3 using relative call stack level. 

i## Add 10 to the value of x in the proc that called stack3 
it (stack2) 
i## Add 100 to the value of x in the proc that called stack2 
# (stack1l) 
i## Add 200 to the value of x in the global scope. 

i## display the value of x using absolute call stack level. 


proc stack3 {} { 


set x 3; 
puts "X in stack3 starts as $x" 
puts "" 


i display the value of x at stack levels relative to the 
df current level. 
for {set i l} {$i <= 3} {incr 7} { 
upvar $i x localXx 
puts "X at upvar $i is $localX" 
} 


puts "\nx is being modified from procedure stack3" 

# Evaluate a command in the scope of procedures above the 
# current call level. 

uplevel 1 {incr x 10} 

uplevel 2 {incr x 100} 

uplevel #0 {incr x 200} 

puts "" 
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} 


## display the value of x at absolute stack levels 


for {set i 


} 


puts 


O} {$1 < 3} {incr i} { 
upvar #$i x localXx 
puts "X at upvar #$i is $localX" 


i## Example Script 

set x 0; 

puts "X in global scope is $x" 
stackl 


puts "X in global scope ends as $x" 


being modified from procedure stack3 


200 
101 
12 


as 12 
as 101 


Script Output 
X in global scope is 0 
X in stack1 starts as 1 
X in stack2 starts as 2 
X in stack3 starts as 3 
X at upvar 1 is 2 
X at upvar 2 is 1 
X at upvar 3 is 0 
x is 
X at upvar #0 is 
X at upvar #1 is 
X at upvar #2 is 
X in stack2 ends 
X in stack1 ends 
X in 


global scope ends as 200 


The scopes in the preceding example resemble the diagram that follows, in which the procedure 
stack3 is being evaluated. Each local procedure scope is nested within the scope of the procedures 
that called it. 

When the uplevel 1 {incr x 10} command is evaluated, it causes the string incr x 10 to be 
evaluated one scope higherthan the current stack3 scope, which is the stack2 scope. The uplevel 
#0 {incr x 200} command is evaluated at absolute scope level 0, or the global scope. The evalu- 
ation level for a command uplevel #1 would be the first level down the call stack, stack1 in this 
example. This example is not a recommended technique for using the command. It is intended only to 
demonstrate how up|] evel works. 
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Global Scope 


All procedure and command names are visible 
All global variables are visible 


Procedure stack1 {} 
Local procedure scope tor stack1 
upvar #0 maps variables in the global scope to the local scope 
upvar 1 maps variables in the global scope to the local scope 


stack! variables are local 
global variables are visible using global command 


Procedure stack2 {} 
Local procedure scope for stack2 


upvar #0 maps variables in the global scope to the local scope 
upvar #1 maps variables in the stack! scope to the local scope 


upvar 1 maps variables in the stack! scope to the local scope 
upvar 2 maps variables in the global scope to the local scope 


stack2 variables are local 
stack1 variables are visible using upvar or uplevel 
global variables are visible using global command 


Procedure stack3 {} 


Local procedure scope for stack3 


upvar #0 maps variables in the global scope to the local scope 
upvar #1 maps variables in the stack! scope to the local scope 
upvar #2 maps variables in the stack2 scope to the local scope 


upvar 1 maps variables in the stack2 scope to the local scope 
upvar 2 maps variables in the stack! scope to the local scope 
upvar 3 maps variables in the global scope to the local scope 


stack3 variables are local 
stack1 and stack2 variables are visible using upvar or uplevel 
global variables are visible using global command 


The preceding example demonstrates how procedures can access all levels above them in the call 
stack but not levels below. The g10bal command works well if you have a single global variable that a 
procedure will manipulate. If your application requires several variables to describe the system’s state, 
the best technique is to use a single associative array and multiple indices to hold the different values. 

If your application has multiple entities that each have their own state, you may use a different 
associative array to describe each entity’s state and use the upvar command to map the appropriate 
array into a procedure. 
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The next example shows a simple two-person game with the players’ positions kept in separate 
global variables. The move procedure may be invoked with the name of either variable, which it maps 
to a local variable called p1 ayer and makes a move for that player. 


————— eee eee ee eee 
Example 12 


Script Example 
set playerl(position) 0 
set player2(position) 0 


proc move {playerName} { 
upvar #0 $playerName player 
i## Move the piece a random number of spaces 
if between 0 and 9. 
set move [expr int(rand() « 10)] 
incr player(position) $move 


} 


while {($playerl(position) < 20) & ($player2(position) < 20)} { 
move playerl 
move player2 
puts "\nCurrent Positions:" 
puts "1: $playerl(position)" 
puts " 2: $player2(position)" 


if {$playerl(position) > $player2(position)} { 
puts "Player 1 wins!" 

} else { 

puts "Player 2 wins!" 


Script Output 
Current Positions: 
1: 8 
2: 3 


Current Positions: 
1: 11 


Current Positions: 
1: 14 
23 17 
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Current Positions: 
1: 19 
2: 25 

Player 2 wins! 


MAKING A TCL OBJECT 


The C++/Java model of object-oriented programming is the most common type of OO programming, 
but it’s not the only OO model. Tcl supports several styles of OO programming from [incr Tcl] 
which is very much like C++ to functional or personal styles of implementing OO concepts. 

This section describes how you can perform simple object-style programming in pure Tcl. This 
discussion and the discussion of namespaces in the next chapter deals with a subset of a complete 
object programming environment. The [incr Tcl] extension and Tc100 package support full object- 
oriented programming. The [incr Tcl] extension is discussed briefly later, and the Tc 100 package 
will be discussed in more detail in the next chapters. 

Chapter 3 mentioned that Tcl keeps separate hash tables for commands, associative array indices, 
and variables, and that the first word in a Tcl command string must be a command name. These features 
mean that any name can be defined as both a variable name and a procedure name. The interpreter will 
know which is meant by the position of the name in the command line. 

This section discusses techniques for using the same label as a variable name or array index and 
a procedure name. In this example, the procedure name is the same as the name of a variable in the 
global-scope. 

This lets us implement the object-oriented programming concept of having methods attached to a 
data object. This implementation of an object is different from the implementation of a C++ or Java 
but the concept of data and method related is similar. 


An Object Example 


For a simple example, the following code creates variables with the name of a common fruit and then 
creates a procedure with the same name that tests whether or not its argument is a valid color for 
this fruit. 

This example uses the info level command to discover the name of the procedure at run time 
and map the variable with that name into the local scope. 


$$ 
Example 13 
Script Example 
## Define a set of fruit names and colors 
set fruitList [list {apples {red yellow green}} \ 
{bananas yellow} \ 
{grapes {green purple}}] 
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foreach fruitDefinition $fruitList { 
i## 1) Extract the name and possible colors from the 
if fruit definition. 


lassign $fruitDefinition fruitName fruitColors 


if 2) Creat global variable named for the fruit, with 
if the fruit colors as a value 


oO 
m@ 


set $fruitName $fruitColors 


i## 3) Define a procedure with the name of the fruit 

if being checked. The default value for "name" is 

if also the name of the fruit, which is also the name 

if of the global variable with the list of fruit colors. 


proc $fruitName {color} { 

set name [lindex [info level 0] 0] 

upvar #0 $name fruit 
if {Llsearch $fruit $color] >= 0} { 

return "Correct, $name can be $color" 

} else { 

return "No, $name are $fruit" 


} 
} 
} 
## 4) Loop through the fruits, and ask the user for a color. 
ld Read the input from the keyboard. 
if Evaluate the appropriate function to check for correctness. 


foreach fruit [list apples bananas grapes ] { 
puts "What color are $fruit?" 
gets stdin answer 
puts [$fruit $answer] 


} 

Script Output 
What color are apples? # User types red 
Correct, apples can be red 
What color are bananas? # User types red 
No, bananas are yellow 
What color are grapes? # User types red 


No, grapes are green purple 
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The first procedure defined resembles this: 
proc apples {color} { 

set name [lindex [info level 0] 0] 

upvar #0 $name fruit 

if {Llsearch $fruit $color] >= 0} { 
return "Correct, $name can be $color" 

} else { 
return "No, $name are $fruit" 


} 


When this procedure is invoked as apples red, the name of the procedure apples is assigned 
to the variable name andthe upvar #0 $name fruit maps the global variable app1es to the local 
variable fruit. 

The code in the previous example can be wrapped into a createFruitObject procedure to create 
both the global variable and procedure. The procedure created in createFruitObject is created in 
the global scope, even though the proc command is in a procedure. 

Data can be represented in several ways in Tcl. To demonstrate the variety of data styles, the 
fruitList is defined as a keyed list instead of a list of lists in the next example. 


ooo —-:.:.—n—nmn— aw _ 
Example 14 


proc createFruitObject {name colors} { 
global $name 
set $name $colors 
proc $name {color} { 
set name [lindex [info level 0] 0] 
upvar #0 $name fruit 
if {[lsearch $fruit $color] >= 0} { 
return "Correct, $name can be $color" 
} else { 
return "No, $name are $fruit" 


set fruitList {apples {red yellow green} 
bananas yellow 
grapes {green purple}} 


foreach {fruit colors} $fruitList { 
createFruitObject $fruit $colors 


} 


foreach fruit [list apples bananas grapes ] { 
puts "What color are $fruit?" 


———S—— | 
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gets stdin answer 
puts [$fruit $answer] 


} 
= 


A functional language type of an object method can be created by embedding the data into the 


procedure, instead of using the name of an external array as the default argument. 


proc createFruitObject {fruitName fruitColors} { 
proc $fruitName [list color [list colors $fruitColors]] { 
set name [lindex [info level 0] 0] 
if {Llsearch $colors $color] >= 0} { 
return "Correct, $name can be $color" 
} else { 
return "No, $name are $colors" 


} 
} 


## Create new fruit commands 
foreach {name colors} {apples {red yellow green} 
bananas yellow 
grapes {green purple}} { 
createFruitObject $name $colors 


.7 BOTTOM LINE 


A procedure can be defined as taking an undefined number of arguments by placing the args 
argument last in the argument list. 

A procedure argument with a default value is defined by declaring the argument as a list. The second 
list element is the default value. 

When a Tcl procedure is evaluated, it creates a local scope for variables. This local scope stacks 
below the scope of the code that invoked the procedure. 

A Tcl procedure can access all of the scopes above it in the procedure call stack. 

Tcl procedures can be constructed and evaluated in a running program. 

Data items can be treated as objects by creating a procedure with the same name as the data item 
and using that procedure to manipulate the data item. 

The rename command renames or removes a command or procedure. 

Syntax: rename oldName ?newName? 

The subst command performs a pass of command and variable substitutions upon a string. 
Syntax: subst string 

The eval command will evaluate a set of arguments as a Tcl command. 

Syntax: eval arg ?args? 

The info subcommands that report information about procedures include the following. 
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Syntax: info procs pattern 
Return a list of procedures that are visible in the current scope and match a pattern. 
Syntax: info commands pattern 
Return a list of commands that are visible in the current scope and match a pattern. 
Syntax: info args procName 
Return the arguments of a procedure. 
Syntax: info body procName 
Return the body of a procedure. 
e The global command declares that a variable exists in the global scope. 
Syntax: global varNamel ?varName2...varNameN? 
e Simple objects can be created by using the same word for both a variable name (or associative array 
index) and the procedure that will manipulate that data. 
e Macintosh users may need to prepend file names with a colon to allow Tcl to recognize file names 
with embedded forward slashes. 


7.8 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5 line script. These problems should each take under a 
minute to answer. 


200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 


800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e 100 What would be the arguments portion of a proc command that duplicated the behavior of the 
Tcl format command? 


e¢ 101 What would be the arguments portion of a proc command that duplicated the behavior of the 
Tcl incr command? 


e 102 After a procedure has returned, can you access any of the local variables that were used in that 
procedure? 


e 103 If procA invokes procB, can procB local variables be accessed from procA? 
e 104 If procA invokes procB, can procaA local variables be accessed from procB? 


e 105 Can you use the rename command to rename Tcl commands, such as while or for? 
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e¢ 106 Under what circumstances would the subst command be preferable to using the set 
command? 


¢ 107 What Tcl command will return the argument list for a procedure? 


e 108 What Tcl command will define a procedure named foo 
a. with a single required argument? 
with a single optional argument with a default value of 2? 
that accepts zero or more arguments? 
that accepts two or more arguments? 
that has one required argument, one optional argument with a default value of 2, and may 
accept more arguments? 


Po oe 


e 109 What Tcl command could be used to determine if a procedure has been defined? 
e 200 Write a procedure that will accept one or more numeric arguments and return their sum. 


¢ 201 Write a procedure that will accept zero or more numeric arguments and return the sum if there 
are multiple arguments, or a 0 if there were no arguments. 


e 202 Write a procedure that will duplicate the functionality of the incr command using the upvar 
command. 


e¢ 203 Write a procedure that will duplicate the functionality of the incr command using the 
up]level command. 


e 300 Write a procedure that will rename the following Tcl commands to new commands. Write a 
short script to test the new commands. 
if -> if, like 
for -> so 
expr -> fuzzyNumbers 


¢ 301 Write a script that will display all permutations of the values of a list of variable names, as 
suggested by the following. 
set-.a 1 
set b 2 
set list fa b} 
showPermutations $list 


with output: 


e 302 Given a procedure report {data} {...} that uses puts to print a report to the screen, write 
a short script to create a new procedure reportFile {data outputChanne]} that will send an 
identical report to an open Tcl channel. 
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303 Write a short script that will compare the bodies of all visible procedures and generate a list of 
procedures with identical bodies. 


304 Write a procedure for the tree. tcl module described in Chapter 6 that will return a list of a 
node siblings (the other child nodes to this node parent). Add a new method to the 
treeObjectProc described in this chapter to evaluate the treeGetSibling procedure. 


305 Write a procedure that will create simple objects. The procedure should accept a variable 
name, value, and body to evaluate when the variable’s procedure is invoked. 


306 Write two procedures, as follows. 


Syntax: class className body 
Adds a new class name to aa collection of known classes and associates 
the body with that class. 

Syntax: new className value 


Creates a variable with a unique name in the global scope, and assigns value to it. Creates a new 
procedure with the same name and single argument args, and uses the body that was defined with 
the class command as the body for the procedure. 

When complete, code such as follows should function. 


class test {return "args are: $args"} 
set x [new test 22] 

puts ‘‘Value of test: [set $x]’’ 
puts ‘‘Results of test: [$x ab c]’’ 


The script output would look as follows. 


Script Output 
Value of test: 22 
Results of test: args are: abc 


CHAPTER 


Namespaces, Packages and 
Modules 


The namespace and package commands implement two different concepts that work together to 
make it easier to write reusable, modular, easily maintained code. The namespace command provides 
encapsulation support for developing modular code. The package command and modules provide 
tools for organizing collections of code into libraries. 

The namespace command collects persistent data and procedure names in a private scope where 
they will not interact with other data or procedure names. This lets you load new procedures without clut- 
tering the global space (avoiding name collisions) and protects private data from unintentional corruption. 

The package command groups a set of procedures that may be in separate files into a single log- 
ical entity. Other scripts can then declare which packages they will need and what versions of those 
packages are acceptable. The Tcl interpreter will find the directories where the packages are located, 
determine what other packages are required, and load them when they are needed. The package 
command can load both Tcl script files and binary shared libraries or DLLs. 

The original package implementation used special files in each directory to list the available pack- 
ages and versions in that directory. As the number of available packages increases, this caused a speed 
issue when applications start. 

Since many packages are contained in a single file the package command was extended to also 
search for files that end with a tm suffix, which are known as modules. The name of the module file 
encodes the package name and revision number. This allows single-file packages to be found by only 
examining directories, not opening and searching files. 

This chapter discusses the following. 


e The namespace scope. 

¢ Encapsulating Tcl procedures and data in namespaces. 

e Nesting one namespace within another. 

e Modularizing Tcl scripts into packages. 

e Creating a Tcl module. 

e Assembling a namespaced library within a package. 

¢ Guidelines for writing modules with relative namespace paths. 


NAMESPACES AND SCOPING RULES 


Chapter 7 discussed the Tcl global and procedure variable scopes. This section expands on that dis- 
cussion and introduces the namespace and variable commands. These commands allow the Tcl 
programmer to create private areas within the program in which procedure and variable names will not 
conflict with other names. 
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8.1.1 Namespace Scope 

Namespaces provide encapsulation similar to that provided by C++ and other object-oriented lan- 
guages. Namespace scopes have some of the characteristics of the global scope and some charac- 
teristics of a procedure local scope. A namespace can be viewed as a global scope within a scope. 
Namespaces are similar to the global scope in that: 


e Procedures created at any procedure scope within a namespace are visible at the top level of the 
namespace. 

e Variables created in a namespace scope (outside a local procedure scope) are persistent and will be 
retained between executions of code within the namespace. 

e Variables created in a namespace scope (outside a local procedure scope) can be accessed by any 
procedure being evaluated within that namespace. 

e While a procedure defined within a namespace is being evaluated, it creates a local scope within 
that namespace, not within the global namespace. 


Namespaces are similar to local procedure scopes in that: 


¢ Code being evaluated within a namespace can access variables and procedures defined in the global 
space. 

e All namespaces are contained within the global scope. 

e Namespaces can nest within each other. 


Namespaces also have the following unique features. 


e A namespace can declare procedure names to be exportable. A script can import these procedure 
names into both the global and other namespace scopes. 
e A nested namespace can keep procedures and variables hidden from higher-level namespaces. 


8.1.2 Namespace Naming Rules 
A namespace can contain other namespaces, creating a tree structure similar to a filesystem. The 
namespace convention is similar to the filesystem naming convention. 


e Instead of separating entities with slashes (/ or \), namespace entities are separated with double 
colons (::). 
e The global scope is the equivalent of a filesystem “/” directory. It is identified as “::”. 
e Namespace identifiers that start with a double colon (::) are absolute identifiers and are resolved 
from the global namespace. 
An entity identified as ::foo::bar::baz represents an entity named baz, in the bar 
namespace, which was created within the fo00 namespace, which was created in the global scope. 
e Namespace identifiers that do not start with a double colon are relative, and are resolved from the 
current namespace. 
An entity identified as bar: :baz represents an entity named baz that is a member of the 
namespace bar, which was created in the current namespace. The current namespace may be the 
global namespace (::) or a child namespace. 


The following diagram shows the scopes in a script that contains two namespaces (example and 
demo), each of which contains procedures named procl and proc2. Because the procedures are in 
separate namespaces, they are different procedures. If a script tried to define two proc! procedures at 
the global level, the second definition would overwrite the first. 
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In this example, :: example: :procl and ::example::proc2 are procedures that are both called 
independently, whereas ::demo::proc2 is called from ::demo::procl. The ::demo::proc2 is 
displayed within ::demo::procl to show that the procedure local scopes nest within a namespace 
just as they nested within the stack example in the previous chapter. 


OOOO -—n—n—n— Oey >= 
Example 1 


Script Example 


i## Define namespace example with two independent procedures. 
namespace eval example { 

proc procl {} {puts "procl"} 

proc proc2 {} {puts "proc2"} 
} 


i## Define namespace demo with a procedure that invokes 
## another procedure within the namespace. 
namespace eval demo { 

proc procl {} {proc2} 

proc proc2 {} {puts "proc2"} 


Global Scope 


all command names are visible in this scope 


all global variables are maintained in this scope 
imported namespace procedures and variables are visible in this scope 


namespace ::example 
defines the namespace scope ::example 
nexample variables are maintained here 
nexample::proci is defined at this scope 
nexample ::proc2 is defined at this scope 
can access global scope 


Can export variables and procedure names 


proc ::example::proct 


local ::example::proc! scope 


canaccess keal (procl) scope 
can access ::example namespace variables 
can access ::example procedures 
canaccess global scope 


prec ::example::proc2 
local ::example::proc2 scope 


can access local (proc2) scope 
can access ::example namespace variables 
can access ::example procedures 
canaccess global scope 


namespace ::demo 
defines the namespace scope ::demo 


udemo variables are maintained here 

ndemo::proci is defined at this scope 

ndemo::proc2 is defined at this scope 
can access global scope 


Can export variables and procedure names 


proc ::demo::proct 
local ::demo::proci scope 


can access local (proc1) scope 
can access ::demo namespace variables 
can access ::demo procedures 
can access global scope 


proc ::demo::proc2 
local ::demo: :proc2 scope 


can access local (proc2) scope 
can access ::demo::proc1 local variables 
can access ::demo namespace variables 
can access ::demo procedures 
can access global scope 
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8.1.3 Accessing Namespace Entities 


In C++, Java, or other strongly object-oriented languages, private data is completely private and other 
objects cannot access it. In Tcl, the namespace encapsulation is advisory. An entity (procedure or data) 
in a namespace can always be accessed if your script knows the full path to that entity. 

A script can publish the procedures within a namespace it considers public with the namespace 
export command. Other scripts can import procedure names from the namespace into their local 
scope with the namespace import command. These commands are discussed later in this section. 
To avoid potential namespace collisions, your scripts should access namespace procedures by their full 
identifier, instead of importing the procedures into the global scope. 


e Using the namespace identifier for an entity makes it easier to figure out what package a procedure 
or data originated from. 

e Using the namespace identifier removes the possibility of name collisions when you load a new 
package with the same procedure and data names. 


If you always access namespace members by their full path, and namespaces do not provide truly 
private data, why should you use a namespace instead of having your own naming convention? 


e The namespace naming conventions are enforced by the interpreter. This provides a consistent nam- 
ing convention across packages, making it easier to merge multiple packages to get the functionality 
you need. 

e Namespaces nest. Scripts being evaluated in one namespace can create a nested namespace within 
that namespace and access the new namespace by a relative name. 

e Namespaces conceal their internal structure from accidental collisions with other scripts and 
packages. Data and procedures named with a naming convention exist in the global scope. 

e A set of code within a namespace can be loaded multiple times in different namespaces without 
interfering with other instantiations of the namespace. 


5 The namespace and variable Commands 


The namespace command has many subcommands, but most Tcl applications will only use the 
eval, export, and import commands. The children command is discussed in this chapter, and 
although not required for using namespaces it provides some information that is useful in determin- 
ing what namespaces exist within which scopes. The namespace scope and namespace current 
commands are useful when namespace procedures may be invoked by an event handler. These 
subcommands are discussed later. 

The namespace eval command evaluates a script within a namespace. The namespace is cre- 
ated, if it does not already exist. The script evaluated by the namespace eval command can define 
procedures and variables within the namespace. 


Syntax: namespace eval namespaceID argl ?argN...? 
Create a namespace, and evaluate the script arg in that scope. If more than one arg is 
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present, the arguments are concatenated into a single script to be evaluated. 
namespaceID The identifying name for this namespace. 


arg* The script or scripts to evaluate within namespace 
namespacelD. 


$$$ $A $a A ee 
Example 2 
it Create a namespace named ‘demo’ 
namespace eval demo { 
proc PrivateProc {} { 
# Do stuff 


} 
proc publicProc {} { 
# Do other stuff 


Once a namespace has been created, new procedures can be added to the namespace either by defining 


them within another namespace eval command or naming them for the namespace they occur in, as 
follows. 


namespace eval demo {} 
proc demo::newProc {} { 
## Do stuff 


Note that namespace eval must be evaluated before defining a procedure within the namespace. 
Namespaces are only created by the namespace eval command. 

It is often necessary to permit certain procedures in one namespace to be imported into other scopes. 
You will probably want to allow the procedures that provide the application programmer interface 
(API) to your package to be imported into other namespaces but not allow the importation of internal 
procedures. 

The namespace export command defines the procedures within one namespace that can be 
imported to other scopes. By convention, procedures that will be exported are given names starting 
with a lowercase letter, whereas procedures for internal use have names starting with capital letters. 


Syntax: namespace export patternl ?patternN...? 
Export members of the current namespace that match the patterns. Exported procedure 
names can be imported into other scopes. The patterns follow g1ob rules. 
pattern Patterns that represent procedure names and data names to be 
exported. 
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Example 3 
i## Create a namespace named ‘demo’ 
namespace eval demo { 

namespace export publicProc publicAPI 
proc PrivateProc {} { 
# Do stuff 


} 
proc publicProc {} { 
# Do other stuff 


} 
} 
proc demo::publicAPI {} {...} 


The namespace import command imports a procedure from one namespace into the current 
namespace. When a procedure that was defined within a namespace is imported into the global 
namespace, it becomes visible to all scopes and namespaces. 


Syntax: namespace import ?-force? ?patternl patternN...? 
Imports variable and procedure names that match a pattern. 

-force If this option is set, an import command will overwrite existing com- 
mands with new ones from the pattern namespace. Otherwise, names - 
pace import will return an error if anew command has the same name 
as an existing command. 


pattern The patterns to import. The pattern must include the namespacelID of 
the namespace from which items are being imported. There will be more 
details on naming rules in the next section. 


$$ 


Example 4 
if Create a namespace named ‘demo’ 
namespace eval demo { 
namespace export publicProc publicAPI 
proc PrivateProc {} { 
# Do stuff 


} 
proc publicProc {} { 
i## Do other stuff}\\ 


} 


} 
proc demo::publicAPI {} {...} 
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## import all public procedures. 
namespace import demo: :pubx 


When naming procedures that may be imported into other namespaces, it is a good rule to avoid 
names that may have collisions. In particular, avoid names that already exist as core Tcl commands. 
For example, a script that imports a modified version of set will develop some difficult-to-debug 
problems. 

Importing procedures using a glob pattern can be fragile. If a namespace imports from multiple 
namespaces, you can get unexpected collisions. It is usually better to explicitly name the procedures 
you need to import. 

For example, if namespace A imports all exported procedures from namespaces B and C, and 
B and C both import procedures from namespace D, there will be an import collision with the B::D:: 
procedures and C::D:: procedure names. 

The Tcl interpreter generates an error when a script attempts to import a procedure that is already 
defined in the current namespace. If the script should redefine the procedures, you can use the - force 
flag with import to force the interpreter to import over existing procedures. 

The namespace children returns a list of the namespaces that are visible from a scope. 


Syntax: namespace children ?namespacelD? ?pattern? 
Returns a list of the namespaces that exist within namespaceID. (If namespacelID is 
not defined, the current namespace is used.) 
?namespaceID? The namespace scope from which the list of namespaces will be 
returned. If this argument is not present, the list of namespaces 
visible from the current namespace will be returned. 


?pattern? Return only namespaces that match a g1ob pattern. If this argu- 
ment is not present, all namespaces are returned. 


$e 
Example 5 
if {Llsearch ::demo:: [namespace children]] == —1l} { 
## The demo namespace was not found 
## Create a namespace named ‘demo’ 
namespace eval demo { 


} 


The variable command allows you to define persistent data within a namespace. It declares that a 
variable exists and may also define an initial value for the variable. The variable command can be used 
within a procedure or in the non-procedure namespace scope. 

When used inside a procedure, the variable command is similar to the g10bal command. It tells 
the interpreter to map a variable with this name in the outer namespace scope into the procedure local 
scope. 


212 CHAPTER 8 Namespaces, Packages and Modules 


When used outside a procedure, the variable command is similar to a global scope assignment. 

A variable defined with the variable command is equivalent to a variable defined in the g1oba| 
scope, except that the variable name is visible only within the scope of the namespace. These variables 
are easily accessed by the procedures in the namespace, but are not visible from the global namespace. 
The variables declared with the variable command are not destroyed when the namespace scope is 
exited. 

Note that the syntax for the variable command is different from the g]obal command. The 
variable command supports setting an initial value for a variable, whereas the global command 
does not. 


Syntax: variable varName ?value? ?varNameN? ?valueN? 
Declare a variable to exist within the current namespace. The arguments are pairs of 
name and value combinations. 
varName The name of a variable. 


?value? Anoptional value for the variable. 


$$$??? 
Example 6 
if Create a namespace named ‘demo’ 
namespace eval demo { 
if namel has no initial value 
variable namel 
if name2 and name3 are initialized 
variable name2 initial2 name3 initial3 


8.1.6 Creating and Populating a Namespace 

The namespace eval command creates a new namespace. Because all arguments with a namespace 
eval command are evaluated as a Tcl script, any valid command can be used in the argument list. This 
includes procedure definitions, setting variables, creating graphics widgets, and so on. 

A namespace can be populated with procedures and data either in a single namespace eval com- 
mand, in multiple invocations of the namespace eval command or by creating procedures named 
with a full namespace path. The following example shows a namespace procedure that provides 
a unique number by incrementing a counter. The uniqueNumber namespace contains the counter 
variable, staticVar. The getUnique procedure, which is also defined within the uni queNumber 
namespace, can access this variable easily, but code outside the uni queNumber namespace cannot. 


——— rs shown 
Example 7 


Script Example 


if Create a namespace. 
namespace eval uniqueNumber { 
# staticVar is a variable that will be retained between 


i 
t 
pu 
pu 


# 


i## scope before impor 
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pu 
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# 


it scope af 
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## evaluations. This declaration defines the variable 


## and its ini 
variable stat 


# al 


ow getUni 


tial 
icVar 0; 


value. 


namespace export getUnique 


## re 


proc 


turn a un 
getUnique { 


} 


{ 


que to be imported into other scopes 


ique number by incrementing staticVar 


df This declaration of staticVar is the equivalent of a 


# global — 
df in the local 


} 
} 


Example Script 
Display 


US 


Display “get*" co 


ts "Before import, 
ts " Linfo com 


mport a 
espace 


1 exporte 
import 


Display “get*" co 
ter import 


ts "After import, 


ES: Linfo com 


Run getUnique a co 
ts "first 


Display 
ts "stati 
ts "stati 


cVar: 


ts "staticVar is: 


if it were not here, 


then a staticVar 


procedure scope would be created. 
variable staticVar; 
return Lincr staticVar]; 


mands that are visi 


global scope has t 


ands get*]\n" 


; 
g 


Unique val: 
ts "second Unique val: 


$ 


embers of the na 
iqueNumber: :* 


ands that are visi 
ng 


lobal scope has th 


ands getx] \n" 


ple times to prove 
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LgetUnique]" 
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the currently visible namespaces: 
ts "Visible namespaces from the global scope are:" 
[namespace children]\n" 


ble in the globa 


hese \"getx\" co 


espace uniqueNu 


ble in the globa 


ese \"getx\" com 


it works 


the current value of the staticVar variable 
[namespace eval uniqueNumber {set staticVar}]" 
cVar: $uniqueNumber::staticVar" 


The next line generates an error condition because 
staticVar does not exist in the global scope. 


mands:" 


ber 


ands:" 
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Script Output 
Visible namespaces from the global scope are: 
::uniqueNumber ::platform ::00 ::tcl 


Before import, global scope has these "get*" commands: 
gets 


After import, global scope has these "get*" commands: 
gets getUnique 


first Unique val: 1 

second Unique val: 2 

staticvar: 2 

staticvar: 2 

can’t read " staticVar": no such variable 
while executing 

"puts "StaticVar is: $staticVar"" 


There are a few points to note in this example. 


e The procedure getUni que can be declared as an exported name before the procedure is defined. 

e After the uniqueNumber namespace is defined, there are four namespaces visible from the 
global scope: the ::uniqueNumber namespace, the ::tcl namespace, the ::00 (Object Ori- 
ented) namespace and the ::platform (platform information). The : : tclnamespace is always 
present when the Tcl interpreter is running. The ::00 and ::platform namespaces are present 
in Tcl version 8.6. Other namespaces may also be present, depending on what packages have been 
loaded. 

e The namespace import ::uniqueNumber::* command imports all exported entities from 
::uniqueNumber into the global scope. 

e The value of the staticVar variable can be accessed via the namespace eval. It can also be 
accessed as :: uniqueNumber::staticVar. 

e The staticVar variable is initialized by the line 
variable staticVar 0 
when the namespace is created. This code is roughly equivalent to placing 
set staticVar 0 
within the arguments to namespace eval, which would cause the variable to be defined at the top 
scope of the uni queNumber namespace. 

e Using the variable varName initValue construct is safer than initializing variables with the 
set command. When the Tcl interpreter searches for a variable to assign the value to, it looks first in 
the local namespace, then in the global namespace. If the variable exists in the current namespace, 
the value is assigned to the variable in the current namespace. If the variable does not exist in the 
current namespace, but does exist in the global namespace, the global variable will be assigned 
the value. If the variable exists in neither namespace, it is created in the current namespace. The 
variable varName initValue will always initialize a variable within the namespace. 
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8.1.7 Namespace Nesting 

Tcl namespaces can be nested within one another. This provides lightweight equivalents of the object- 
oriented concepts of inheritance (the is-a relationship) and aggregation (the has-a relationship). Note 
that even using namespaces, pure Tcl is not quite a real object-oriented language. The [incr Tcl] 
and Tc100 extensions use namespaces to support the complete set of object-oriented functionality, 
and smaller packages such as stooop and snit provide frameworks for lighter-weight (and fewer- 
featured) object-style programming. The [incr Tc1] extension is discussed in Chapter 17. 

A namespace can be used to create an object. It can inherit functionality and data from other names- 
paces by nesting those namespaces and importing procedures into itself. Procedures can be imported 
from any namespace, regardless of where the namespace is located in the hierarchy. If the namespace 
being imported from only includes procedures, your script can create a single copy of that namespace 
in the global scope, and import from there to as many objects as it creates. 

However, if the namespace being imported from also includes variables, you need a copy of the 
namespace to hold a separate copy of the variables for each object your script creates. In this case, it is 
simplest to nest the namespaces, rather than keep multiple copies at the global scope. 

Note that using namespaces to implement inheritance is implemented in the opposite way as C++ 
or Java-style inheritance. In C++ and Java, a child class inherits functionality down from a parent, 
whereas in Tcl a primary namespace can inherit functionality up from a nested namespace. 

If two or more namespaces need functionality that exists in a third namespace, there are a couple of 
options. They can create a shared copy of the third namespace in the scope of the first two namespaces, 
or each can create a copy of the third namespace nested within its own namespace. 

One advantage of nesting the third namespace is that it creates a unique copy of the persistent data 
defined within the third namespace. If a namespace is shared, that data is also shared. 

Note that whereas procedures can be imported from any namespace, regardless of parent/child 
relationship, variables cannot be imported. If your design requires separate copies of data, you must 
have separate copies of the namespace. The namespace copies can be placed at any position in the 
namespace hierarchy, but it is simplest to inherit the functionality from child namespaces. 

The next example shows the uniqueNumber namespace being shared by two separate names- 
paces (Packagel and Package2). Since the counter is shared between the two namespaces, the 
unique numbers are never duplicated. The example after this shows how two namespaces can have 
the uniqueNumber namespace nested within them so that each namespace gets a full set of unique 
numbers with no gaps. 


——— ee OO 
Example 8 


Script Example 


i## These commands create a uniqueNumber namespace in the scope of 
## the script that invokes it. 
namespace eval uniqueNumber { 
variable staticVal 0 
namespace export getNext; 
proc getNext {} { 
variable staticVal 
return [incr staticVal] 
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it Create the uniquel namespace, 

it Create a counter namespace within the uniquel namespace 

i## The Packagel namespace includes a procedure to return unique 
## numbers 


namespace eval uniquel { 
namespace import ::uniqueNumber:: getNext 
proc example {} { 
return "“uniquel::example: LgetNext]" 


} 


it Create the unique2 namespace, 

i## Create a counter namespace within the unique2 namespace 

i## The unique2 namespace includes a procedure to report unique 
## numbers 


namespace eval unique2 { 
namespace import ::uniqueNumber: :getNext 
proc example {} { 
return "“unique2::example: LgetNext]" 


## Example Script 


puts niquel example returns: [::uniquel::example] 
puts “invoking uniquel::getNext directly returns: \ 
Luniquel::getNext]" 

puts “uniquel example returns: [::uniquel::example]" 
puts." 

puts “unique2 example returns: [ nique2::example]" 
puts “unique2 example returns: [ nique2::example]" 
puts “unique2 example returns: [ nique2::example]" 

Script Output 


uniquel example returns: uniquel::example: 1 
invoking uniquel::getNext directly returns: 2 
uniquel example returns: uniquel::example: 3 


unique2 example returns: unique2::example: 4 
unique2 example returns: unique2::example: 5 
unique2 example returns: unique2::example: 6 


In the next example, the uni queNumber namespace is created inside the uniquel and unique2 
namespaces. There are two staticVal variables—uniquel::uniqueNumber::staticVal and 
unique2::uniqueNumber::staticVal. 
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eee 
Example 9 


Script Example 


# This string of commands creates a uniqueNumber namespace 
## in the scope of the script that invokes it. 


proc createUnique {} { 
uplevel 1 
namespace eval uniqueNumber { 
variable staticVal 0 
namespace export getNext; 
proc getNext {} { 
variable staticVal 
return [incr staticVal] 


a 


} 
} 
namespace import uniqueNumber: :getNext 
} 
} 


i## Create the uniquel namespace, 

i## Create a uniqueNumber namespace within the uniquel namespace 
i## The Packagel namespace includes a procedure to return unique 
## numbers 


namespace eval uniquel { 
createUnique 
proc example {} { 
return "“uniquel::example: [LgetNext]" 


} 


it Create the unique2 namespace, 

i## Create a uniqueNumber namespace within the unique2 namespace 
i## The unique2 namespace includes a procedure to report unique 
## numbers 


namespace eval unique2 { 
createUnique 
proc example {} { 
return "“unique2::example: [LgetNext]" 


} 


## Example Script 

puts "“uniquel example returns: [::uniquel::example]" 

puts “invoking uniquel::getNext directly returns: \ 
[uniquel::getNext]" 

puts "“uniquel example returns: [::uniquel::example]" 
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wu 


puts 
puts “unique2 example returns: [::unique2::example]" 
puts “unique2 example returns: [::unique2::example]" 
puts “unique2 example returns: [::unique2::example]" 


Script Output 
uniquel example returns: uniquel::example: 1 
invoking uniquel::getNext directly returns: 2 
uniquel example returns: uniquel::example: 
unique2 example returns: unique2::example: 
unique2 example returns: unique2::example: 


WN RP WwW 


unique2 example returns: unique2::example: 


Note that the createUni que process uses the up]evel to force the namespace eval to happen at 
the same scope as the code that invoked createUni que. By default, a procedure will be evaluated in 
the scope in which it was defined. Since the createUni que procedure is created in the global scope, it 
will by default create the getNext namespace as a child namespace of the global space. By using the 
uplevel command, we force the evaluation to take place in the scope of the calling script: within the 
package namespace. The following illustration shows what the namespaces look like after evaluating 
the previous example. 


Global Scope 


namespace ::unique1 
detines the namespace scope ::unique1 
procedure unique1::example is defined in this scope 


namespace counter is included in this namespace 
counter::getNext is imported 


namespace ::unique1::counter 
variable staticVal exists in this scope 


procedure counter::getNext is detined in this scope 
getNext is exported 


namespace ::unique2 
defines the namespace scope ::unique2 


procedure unique2::example is defined in this scope 


namespace counter is included in this namespace 
counter::getNext is imported 


namespace ::unique2::counter 


variable staticVal exists in this scope 
procedure counter::getNext is defined in this scope 
getNext is exported 
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Namespaces can be used to implement aggregation by including multiple copies of another names- 
pace (complete with data) in child namespaces. For example, a simple stack can be implemented as 
follows. 


set stackDef { 
variable stack {} 
proc push {value} { 
variable stack 
lappend stack $value 
} 
proc pop {} { 
variable stack 
set rtn Llindex $stack end] 
set stack Llrange $stack 0 end-1] 
return $rtn 


proc peek {{pos end}} { 
variable stack 
return [lindex $stack $pos] 


proc size {} { 
variable stack 
return [llength $stack] 


} 


The Tower of Hanoi puzzle is 3 posts with rings of various sizes on them. At the beginning, all 
of the rings are on the left most stack, with the largest at the bottom and the smallest on the top. The 
object of the puzzle is to move the rings to another post. The trick is that you can only place a smaller 
ring on top of a larger ring. 

The example below uses the stackDef string to create three stacks within the Hanoi namespace 
to implement a text-only version of the Tower of Hanoi puzzle. The rings are represented by a number 
from | to 4, which is the size of the ring. 

A move is made by popping a value off the top of one stack and pushing it onto the top of another 
stack. 

The stacks are displayed using the format and string repeat commands. 


eee 
Example 10 


Script Example 


namespace eval Hanoi { 
namespace eval left $stackDef 
namespace eval center $stackDef 
namespace eval right $stackDef 
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## proc moveRing {from to}-- 
if Move the last element of the "from" stack 
jf to the end of the "to" stack. 
dt 
if Arguments 
i## from: The name of the stack to move from. 
if to: The name of the stack to move to. 
if Results 
i## The "from" and "to" stacks are modified. 
proc moveRing {from to} { 

${to}::push [${from}::pop] 


} 
proc show {} { 
puts "" 
for {set p 4} {$p >= 0} {incr p -1} { 
set out "" 
foreach stack {left center right} { 
set ring [${stack}::peek $p] 
if {$ring ne ""} { 
set 1 [format “5s [string repeat - $ring]] 
set r [format %-5s [string repeat - $ring]] 


} else { 
set 1 [format 45s " "J 
set r $ 
} 
append out [format %s%s%s $1 "||" $r] 
} 
puts $out 
} 
puts "" 


} 


proc start {} { 
variable left 
if Fill the left stack 
for {set i 4} {$7 > 0} {incr i -1} { 
left::push $i 
} 
} 


proc done {} { 
if {Lright::size] == 4} { 
return 1 
} else { 
return 0 
} 


8.1 Namespaces and Scoping Rules 221 


} 
Hanoi::start 


array set abbr {1 left r right c center} 
while {!CHanoi::done]} { 
Hanoi::show 
puts -nonewline "From (lcr): 
flush stdout 
set from [gets stdin] 
puts -nonewline "To (lcr): 
flush stdout 
set to [gets stdin] 
Hanoi::moveRing $abbr($from) $abbr($to) 


} 


" 


" 


Script Output 


From (lcr): 1 <== User Types 1 
To (ler): c <== User Types c 


From (lcr): 1 <== User Types 1 
To (ler): r == User Types r 


From (lcr): c <== User Types c 
To. (Ler): + <== User Types r 
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8.1.8 Namespace Ensembles 


The namespace ensemble command makes it easier to write commands that mimic the “C” layer 
commands that have subcommands, and it provides a tool for better pure-Tcl object-style programming. 
We’ll examine the Tower of Hanoi again in the discussion of TclOO. 

One problem with the code above is that the procedures in the stackDef are duplicated in each of 
the left, center and right namespaces. In this example, the procedures are small and there are only three 
of them. In other applications the procedures might be large, or there might be many of them, and the 
duplication could become a machine resource issue. 

Another problem is that the code is slightly ugly with the need to escape variable names and include 
all the double colons. 

Tcl 8.5 introduced the namespace ensemble command to namespaces. This command makes it 
easy to treat a namespace like a procedure and procedures within a namespace as if they were sub- 
commands for that command. The ensemble commands can be invoked like regular Tcl commands, 
without the : : separators. 

For example, instead of left: :push we can write left push. 

The namespace ensemble command has a few sub commands. The one that creates a new 
ensemble command is namespace ensemble create. 


Syntax: namespace ensemble create -map ensName script 
Create an ensemble command to map a command name in the current scope to different 
command. 


ensName The ensemble name of the command. 
script The script to evaluate when this ensemble command is invoked. 


The previous code can be rewritten to use an ensemble as shown below. In the new code, the stack 
variable exists within the left, center and right namespaces, rather than being embedded within 
that namespace. The commands exist in the shared stackCmds namespace, rather than being repeated 
in each post’s namespace. 

The next example also uses the namespace current command to identify the appropriate stack 
list. The namespace current command returns the fully qualified name of the namespace scope in 
which code is being evaluated. This is useful when code within a namespace is registered for callback 
operation using the trace, fi leevent, etc. commands or if it is used as a callback from a Tk Widget 
(which will be discussed in Chapter 11). 


Syntax: namespace current 
Returns the fully qualified name of the current namespace. 


eee 
Example 11 


Script Example 


namespace eval foo { 
namespace eval bar { 
namespace eval and { 
namespace eval grill { 
} 


namespace eval 
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::foo::bar::and {namespace eval grill { 


puts "Current namespace is [namespace current ]" 


} 
} 


Current namespace is 


::foo::bar::and::grill 


Notice that the code below doesn’t need extra curlie braces to delimit the variable names. The 


normal Tcl spacing is sufficient. 


namespace eval stackCmds { 
proc push {name val} 


upvar $na 


{ 


e stack 


lappend stack $val 


} 


proc peek {na 
upvar $na 
return [1] 


proc size {name} { 


upvar $na 
return [1 


proc pop 


{name} { 


e stack 
ength $stack] 


upvar $name stack 
set rtn [Llindex $stack end] 
set stack [lrange $stack 0 end-1] 
return $rtn 


} 
} 


set stackDef 


{ 


e {pos end}} { 
e stack 
index $stack $pos] 


df Stack variable is maintained in each stack 
variable stack {} 


## Commands are taken from stackCmd namespace 
namespace ensemble create -map [list \ 


peek 
size 
push 
pop 


::StackCmds: 
::StackCmds: 
::StackCmds: 
::StackCmds: 


:peek [namespace 
:size [namespace 
:push [namespace 
> pop 


[namespace 


current]: 
current]: 
current]:: 
current]: 


:stack" 
:stack" 


stack" 


:stack"] 


\ 
\ 
\ 
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namespace eval Hanoi { 
namespace eval left $stackDef 
namespace eval center $stackDef 
namespace eval right $stackDef 


{HEHHAAARA EAA AAA AAA AAP 


## proc moveRing {from to}-- 

if Move the last element of the "from" stack 
if to the end of the "to" stack. 

dt 

if Arguments 

if from: The name of the stack to move from. 
if to: The name of the stack to move to. 

if Results 

i## The "from" and "to" stacks are modified. 


proc moveRing {from to} { 
to push [$from pop] 


proc show {} { 
for {set p 4} {$p >= 0} {incr p -1} { 
set out "" 
foreach stack {left center right} { 
set ring [$stack peek $p] 
if {$ring ne ""} { 
set 1 [format “5s [string repeat - $ring]] 
set r [format %-5s [string repeat - $ring]] 


} else { 
set 1 [format 45s " "J 
set r $ 
} 
append out [format %s%s%s $1 "||" $r] 
} 
puts $out 


} 
puts 
} 


proc start {} { 
variable left 
if Fill the left stack 
for {set i 4} {$7 > 0} {incr i -1} { 
left push $i 
} 
} 


proc done {} { 
if {Lright size] == 4} { 
return 1 
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} else { 
return 0 
} 
} 
} 
Hanoi::start 


array set abbr {1 left r right c center} 
while {!CHanoi::done]} { 
Hanoi::show 
puts -nonewline "From (lcr): 
flush stdout 
set from [gets stdin] 
puts -nonewline "To (lcr): 
flush stdout 
set to [gets stdin] 
Hanoi::moveRing $abbr($from) $abbr($to) 
} 


This section described creating nested namespaces by using a procedure or using a Script string. 
These techniques require the child namespace code to be resident in the script that uses it. The next 
section discusses how packages can be used to find and load appropriate scripts from other files, and 
then describes how to nest namespaces contained within a package. 


8.2 PACKAGES 


The namespace command allows you to assemble related information and procedures within a private 
area. The package commands allow you to group a set of procedures that may be in multiple files and 
identify them with a single name. The namespace command provides encapsulation functionality, 
whereas the package command provides library functionality. This section describes how to turn a set 
of procedures into a package other scripts can load easily. 

People frequently refer to any collection of procedures and variables that work together to perform 
related functions as a package. A real Tcl package is a collection of procedures that can be indexed 
and loaded easily with the package command. The actual code may be identified using the package 
commands discussed first, or the module naming convention that will be discussed later. 

The package provide command defines a set of procedures that can be a part of a package 
identified by the package name and a revision number. These procedures can be indexed and can be 
loaded automatically when they are needed by another script. The Tcl package command provides a 
framework for the following. 


e Finding and loading the code modules a script requires. 

e Tracking the version numbers of packages and loading the proper version. 

e Defining whether the file to be loaded is a script file (discussed here) or shared library/DLL 
(discussed in Chapter 15). 

e A single file package may be identified by including the file in the module search path and using a 
file name that conforms to the modu e naming convention instead of using the package commands 
to create the package. 
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8.2.1 How Packages Work 
A Tcl package includes an index file that lists the procedures and commands defined in the package. 
The Tcl interpreter resolves unknown procedures by searching the index files in the directories listed 
in the global variable auto_path for required packages. The auto_path variable is defined in the 
init.tcl script, which is loaded when a Tcl or Tk interpreter is started. 

This section describes creating the index files and adding your package directories to the list of 
places the interpreter will search. Note that when you create an index for a package that has procedures 
defined within a namespace, only the procedure names listed ina namespace export command will 


be indexed. 


8.2.2 Internal Details: Files and Variables Used with Packages 


The following files and global variables are used to find and load a package. 


pkgIndex.tcl file 


auto_path 


These files contain a list of procedures defined by the packages in the directory 
with this file. The pkgIndex.tcl files are created with the pkg_mkIndex 
command. 


global variable 


The auto_path variable contains a list of the directories that should be 
searched for package index files. 


The auto_path variable is defined in the init.tcl script, which is loaded 
when a tcl sh interpreter is started. 


On UNIX systems, init.tcl will probably be found in /usr/local/ 
lib/tcl8.6, /opt/Activelcl8.6/1ib or some variant, depending on 
your installation and the revision number of your tcl sh. 


On Windows systems, init.tcl is stored in \Program Files\ 
Tcl\lib\tcl8.4, or some variant, depending again on your version of 
Tcl and the base directory in which you installed the Tcl interpreter. 


On Macintoshes running OS8 or earlier, the init.tcl file may be stored 
in Tcl/Tk Folder 8.4:Tcl:library, again depending on installation 
options. 

On Mac OS/X, the init.tcl file may be stored in /Library/Frameworks 
/Tcl.framework/Versions/ 8.6/Resources/Scripts/init.tcl, 
again depending on installation options. 


When the Tcl interpreter is trying to find a package to fulfill a package 
require command, it will search all of the directories listed in the auto_path 
variable, and all of the children in those directories, but not second-level sub- 
directories of the directories listed. This makes it possible to place a single 
directory in the auto_path list, and use separate directories under that for 
each supported package. 


8.2 Packages 227 


8.2.3 Package Commands 


The package functionality is implemented with several commands. These commands convert a simple 
script into a package. The pkg_mk Index command creates a package index file. It is evaluated when a 
package is installed rather than when a script is being evaluated. 

The pkg_mkIndex command scans the files identified by the patterns for package pro- 
vide commands. It creates a file (pkgIndex.tcl) in the current directory. The pkgIndex.tcl file 
describes the commands defined in the package, and how to load the package when a script requires 
one of these commands. 


Syntax: pkg_mkIndex ?-option? dir pattern ?pattern? 
Creates an index of available packages. This index is searched by package require 
when it is determining where to find the packages. 
?-option? An option to fine-tune the behavior of the command. The option set has 
been evolving, and you should check the documentation on your system 
for details. 


dir The directory in which the packages being indexed reside. 
pattern* Glob-style patterns that define the files that will be indexed. 


When the pkg_mk Index command has finished evaluating the files that match the pattern argu- 
ments, it creates a file named pkgIndex.tcl in the dir directory. The pkgIndex.tcl file contains 
the following. 


e The names of the packages defined in the files that matched the patterns. 
e The version level of these packages. 

e The name of the command to use to load the package. 

¢ Optionally, the names of the procedures defined in those packages. 


The pkg_mk Index will overwrite an existing pkgIndex.tcl file. If you are developing multiple 
packages in a directory, you will need to enter the name of each file every time you update the index. 
In this case, it may become simpler to create a two-line script that lists all files, as follows. 


#!/usr/local/bin/tclsh 
pkg_mkIndex [pwd] filel.tcl file2.tcl file3.tcl 


The package provide command defines the name and version of the package that includes these 
procedures. This command makes the procedures defined within the file available to other scripts. 


Syntax: package provide packageName ?version? 
Declares that procedures in this script module are part of the package packageName. 
Optionally declares which version of packageName this file represents. 
packageName The name of the package that will be defined in this script. 
?version? The version number of this package. 


The pkg_mk Index command looks fora package provide command ina file. It uses the package 
name and version information to generate an entry in the pkgIndex.tcl file with the name and version 
of the package and a list of procedures defined in this file. 

The package provide command tells the Tcl interpreter that all of the procedures in the file 
are members of a package. You can use multiple files to construct your package, provided there is a 
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package provide command in each file. Note that if you have multiple package provide com- 
mands with different packageName or version arguments in a source file, the pkg_mk Index will not 
be able to generate an index file, and may generate an error. 

## Declare this file part of myPackage 

package provide myPackage 1.0 


The package require command declares that this script may use procedures defined in a 
particular package. Scripts that require procedures defined in other files will use this command. 


Syntax: package require ?-exact? packageName ?versionNum? 
Informs the Tcl interpreter that this package may be needed during the execution of 
this script. The Tcl interpreter will attempt to find the package and be prepared to load 
it when required. 
-exact If this flag is present, versionNum must also be present. The Tcl 
interpreter will load only that version of the package. 


packageName ‘The name of the package to load. 


?versionNum? The version number to load. If this parameter is provided, but 
-exact is not present, the interpreter will allow newer versions of 
the package to be loaded, provided they have the same major ver- 
sion number (see Section 8.2.4 for details of version numbering). If 
this parameter is not present, any version of packageName may be 
loaded. 


————————— eee eee 
Example 12 


i## This program needs to load myPackage 
package require myPackage 1.0 
el 

The package require command checks the pkgIndex.tcl files in the search path (defined in 
auto_path) and selects the best match to the version number requested. If the -exact flag is used, 
it will select an exact match to that version number. If vers ionNum is defined and the - exact is not 
set, the largest minor revision number greater than versionNum will be selected. If versionNum is 
not defined, the highest available version will be selected. If an acceptable revision cannot be found, 
package require will generate an error. 

If the Tcl interpreter can locate an appropriate package, it will load the required files as necessary 
to resolve the procedures defined in the package. Older Tcl versions (prior to 8.2) deferred loading 
packages until the procedures were needed. Since 8.2 the default behavior is to load packages imme- 
diately. The older, Just-In-Time style of loading can still be used by including the - 1azy option to the 
pkg_mk Index command when you create the pkgIndex.tcl file. 

The packages loaded by package require are loaded into the global namespace. 


.4 Version Numbers 


The package command has some notions about how version numbers are defined. The rules for 
version numbers are as follows. 
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e Version numbers are one or two positive integers separated by periods (e.g., 1.2 or 75.19). 

e The first integer in the string is the major revision number. As a general rule, this is changed only 
when the package undergoes a major modification. Within a major revision the API should be 
constant and application code should behave the same with later minor revision numbers. Between 
major revisions, there may be changes such that code that worked with one major revision will not 
work with another. 

e The second integer is the minor revision number. This corresponds to an intermediate release. You 
can expect that bugs will be fixed, performance enhanced, and new features added, but code that 
worked with a previous minor revision should work with later minor revisions. 

e The Tcl interpreter compares revision numbers integer by integer. Revision 2.0 is more recent than 
revision 1.99. 


8.2.5 Package Cookbook 


This section describes how to create and use a Tcl package. The next section will show a more detailed 
example. 


Creating a Package 

1. Create the Tcl source file or files. You can split your package procedures across several files if you 
wish. 

2. Add the command 
package provide packageName versionNumber 
to the beginning of each of these Tcl source files. 

3. Invoke tclsh. If you have several revisions of Tcl installed on your system, be certain to invoke 
the correct tcl sh. The package command was introduced with revision 7.5 and has been modified 
slightly in successive versions of Tcl. 

4. At the % prompt, type 
pkg_mkIndex directory fileNamePattern ?Pattern2...? 

You may include multiple file names in this command. The pkg_mkIndex command will cre- 
ate a new file named pkgIndex.tcl, with information about the files that were listed in the 
pkg_mk Index command. 


In Tcl version 8.2 and more recent, the default option is to create a pkgIndex.tcl file that loads 
packages immediately. Older versions of Tcl created pkgIndex.tcl files that would defer loading 
until a procedure was needed. This behavior can be duplicated in newer interpreters with the - 1] azy 
option to pkg_mk Index. 


Using a Tcl Package 
1. If the package is not located in one of the Tcl search directories listed by default in the auto_path 
variable, you must add the directory that contains the package’s pkgIndex.tcl] file to your search 
list. This can be done with one of the following techniques. 
A. Add a line resembling 
lappend auto_path /usr/project/packageDir 
to the beginning of your Tcl script. 


230 CHAPTER 8 Namespaces, Packages and Modules 


B. Set the environment variable TCLLIBPATH to include your package directory. The environment 
variable need not include the path to the default Tcl library. Note that TCLLIBPATH is a Tel-style 
whitespace-delimited list, rather than the shell-style colon-delimited list. 

C. Add your package directory to the auto_path definition in the init.tcl file. This file is 
located in the Tcl library directory. The location of that directory is an installation option. 
Modifying the init.tcl script will require continuing the nonstandard modification every 
time the Tcl interpreters are updated. This can make a system fragile. 

2. Add the line 


package require packageName ?versionNumber? 


to load the package into the global namespace. 


8.3 TCL MODULES 


The package system is very versatile. A package can include one or more files. A file in a package can 
be either Tcl code or a loadable compiled library. 

This versatility comes at a cost. In order to find a package the Tcl interpreter must look through 
every directory and subdirectory for pkg_index.tcl files, open, and scan them for appropriate 
packages. 

Many packages can fit into a single file. The module system uses a file naming convention to 
identify a module, saving a few steps over the package system. 

To be used as a module a package must conform to a few conventions: 


1. A module must be a single file with a filename in the format NAME-VERSION.tm. The NAME section 
must start with a letter, after which it may be alphanumeric. The VERSION section must be digits or 
a period. 

2. A module must include a package provide command. 

3. The package provided in the package provide command must match the NAME portion of the 
filename. 

4. The version provided in the package provide command must match the VERSION portion of the 
filename. 


A simple module would resemble this: 


$> cat testmod-1.2.tm 
package provide testmod 1.2 
proc testmodCmd {} { 

puts "testmod is loaded OK" 
} 


The module system makes use of namespaces, which were not part of Tcl when the package 
system was developed. Rather than use a global variable auto_path to define the directories to be 
searched, the module system keeps a hidden variable and provides an API to query and modify the list 
of folder to be examined for modules. 
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Syntax: ::tcl::tm::path add path 
Add a directory to the beginning of the list of directories to be searched for a module. 
path A full or relative path to the directory to be added to the list. 


The ::tcl::tm::path add command enforces that the directories to be searched are not duplicated 
and are not children of other folders in the search path. 

Your script should not need to examine the search path or remove directories from the search path. 
The commands to examine and reduce the search list can be useful during debugging. 


Syntax: ::tcl::tm::path list 
Returns the list of directories to be searched for a module. 


eee ee ee eee 
Example 13 


Script Example 


## Add the current folder to the search path if it 

if is not already in the set of directories to be searched. 

if {Llsearch [::tcl::tm::path list] Lpwd]] < 0} { 
::tcl::tm::path add [pwd] 

} 


A path can be removed from the list with the ::tcl::tm::path remove command. This can be 
useful if you have a test version of a module and you want to be certain to load your new module, not 
the ones in your normal search path. 
Syntax: ::tcl::tm::path remove path 
Remove a directory from the list of directories to be searched for a module. 
path A full or relative path to the directory to be removed to the list. 


8.4 NAMESPACES AND PACKAGES 


Namespaces and packages provide different features to the Tcl developer, with namespaces provid- 
ing encapsulation support and packages providing modularization/library support. A package can be 
written with or without using a namespace. (In fact, packages were added to Tcl a couple years before 
namespace support was added.) The three namespace options when developing a package are: 


e Use no namespaces. The package can be loaded into the global scope or merged into a script- 
defined namespace. This option is suitable for small special-purpose packages that will not conflict 
with other packages, or are intended to always be merged into another namespace. This is not a 
recommended technique, but may be appropriate under some circumstances. 

e Require the package be created in a given namespace. The package uses an absolute name for 
the namespace in the namespace eval command, and uses absolute names to define procedures 
used within the namespace. This is appropriate for packages that add new language features (for 
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example, communications protocols, database connections, and http support) that do not include 
data structures that are specific to a given instantiation. 

e Allow the package to be created in an arbitrary namespace. The package uses a relative name for 
the namespace in the namespace eval command, and uses relative names to define procedures 
used within the namespace. This is appropriate for code modules that contain state information that 
is specific to a given instantiation of the namespace. Complex data structures (such as trees and 
stacks or GUI objects that maintain state information) are examples of this type of design. 


Note that nesting namespaces requires that code be duplicated as well as data. If you have an 
application that creates many objects, you may run into memory constraints. In that case, you may 
need to separate procedures and variables into separate namespaces in order to have nested copies of 
the namespaces with data, and import procedures from a single copy of the code namespace. There are 
a few techniques that can be used to ensure a script will be namespace neutral. 


e Use only relative namespace identifiers. Namespace names that start with a double colon (: :) are 
absolute and are rendered from the global scope. Namespaces that start with a letter are relative 
names and are resolved from the current namespace. 

e Define procedures within the namespace eval, or with relative namespace names. 
namespace eval bad { 

variable badVar 
} 
proc ::bad::badProc {} { 
variable badVar 
set badVar "Don’t Do This" 
} 
namespace eval good { 
variable goodVar 
proc goodProcl {} { 
variable goodVar 
set goodVar "OK" 


} 


} 
proc good::goodProc2 {} { 


variable goodVar 
set goodVar "Also OK" 
} 
e Use namespace current ora relative name to identify the current namespace. The namespace 
current command is discussed in Chapters 11 and 14. 
e Use the variable command to map namespace variables into procedures within the namespace 
rather than using namespace pathnames for variables. 
namespace eval bad { 
variable badVar 
proc badProc {} { 
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Set ::bad::badVar "Don’t Do This" 


} 


namespace eval good { 
variable goodVar 
proc goodProc { 
variable goodVar 
set goodVar OK 


} 


The package require command will load packages into the toplevel (::) namespace. If you wish 
to force a package to be loaded into a child namespace, you must work around the normal behavior. 
The package system uses the auto_index global array to hold the names of procedures defined in 
required packages so that they can be loaded automatically when needed. This can be used to work 
around the normal behavior of the package system as described below. 


1. Your package must export at least one procedure in the package’s namespace scope. 

2. Create a pkgIndex.tcl using the pkg_mk Index command with the -lazy option. 

3. Within the application that requires a package, evaluate the command that Tcl has saved in 
::auto_index(procedureName). 


An example is shown below: 


if cat tstPkg.tcl 
package provide tstPkg 1.0 
namespace eval tstPkg { 
namespace export sampleProc 
proc sampleProc {} {puts "[namespace current]"} 


it tclsh 
pkg_mkIndex -lazy . tstPkg.tcl 


if cat useTstPkg.tcl 
lappend auto_path . 
package require tstPkg 
namespace eval tstInChild { 
eval $::auto_index(::tstPkg::sampleProc) 
} 
tstInChild::tstPkg::sampleProc 


## OUTPUT from tclsh useTstPkg.tcl 


tstInChild::tstPkg 
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8.5 HANOI! WITH A STACK NAMESPACE AND PACKAGE 


The previous version of the Tower of Hanoi puzzle code included a set of stackCmds that implemented 
the three stacks of rings. A stack is a primitive data structure that’s useful for many types of processing, 
including parsing XML and HTML. 

A set of stack procedures is the type of tool that should be generalized and put into a package where 
other applications can access it. 

The next example shows the namespace with stackCmds from the previous Tower of Hanoi 
example converted to a package. The stack operations, push, pop, etc. remain as they were in the 
previous example. The stackDef string of commands to create ensemble commands is moved into 
the namespace and a new command is added to create a stack. 

The createStack command provides a level of implementation hiding. In the previous version 
of the stack, the Tower of Hanoi code had intimate knowledge of the stack implementation. Since the 
stack and puzzle code were designed to run from a single file, this was appropriate. 

When the stack is made generally available to other applications, it’s better to hide the internal 
details from an application developer. 

Notice that the namespace ensemble create command that maps ::stack- 
Cmds::createStack to stackCmds createStack is not within a procedure. This is code 
that’s evaluated when the stack code is loaded by a package require stackCmds command. 


—————— eee ee eee 
Example 14 


Stack Package 
package provide stackCmds 1.0 


namespace eval stackCmds { 


i## Define a set of commands that will be used to create an 
if ensemble version of the stack. 
variable stackDef { 

if stack variable is maintained in each stack 

variable stack {} 


i## Commands are taken from stackCmd namespace 
namespace ensemble create —map [list \ 


peek "::stackCmds::peek [namespace current]::stack" \ 
size "::stackCmds::size [namespace current]::stack" \ 
push "::stackCmds::push [namespace current]::stack" \ 
pop "“::stackCmds::pop [namespace current]::stack"] 


} 


if Make the createStack procedure an ensemble command 


namespace ensemble create —map { 
createStack "::stackCmds::createStack" 


} 


proc createStack {stackName} { 
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variable stackDef 
uplevel 1 [list namespace eval $stackName $stackDef ] 


} 


proc push {name val} { 
upvar $name stack 
lappend stack $val 


} 


proc peek {name {pos end}} { 
upvar $name stack 
return [lindex $stack $pos] 
} 


proc size {name} { 

upvar $name stack 

return [llength $stack] 
} 


proc pop {name} { 
upvar $name stack 
set rtn Llindex $stack end] 
set stack Llrange $stack 0 end—1] 
return $rtn 


This package is wholly contained in a single file and is suitable for being treated like a Tcl module. 
Saving the code in a file named stackCmds-1.0.tm allows a package require command to find 
the package without creating a pkg-index.tcl file. 

Only a few lines of the previous Tower of Hanoi code need to be modified. The differences in the 
first few lines are shown below. 

The current working directory is not normally checked for packages. In this example, the package is 
in the same directory as the mainline Tower of Hanoi code. The first new line adds the current directory 
to the module search path. 

The stackCmds and stackDef code have been moved to the package and replaced by the 
package require command. 

The code to create the three posts is replaced by calls to the stackCmds createStack namespace 
ensemble commands. 


$$ 
Example 15 
Tower of Hanoi Changes 

:itcl::tm::path add. 

package require stackCmds 
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namespace eval Hanoi { 
stackCmds createStack left 
stackCmds createStack center 
stackCmds createStack right 


8.6 CONVENTIONS AND CAVEATS 


It is a common convention in Tcl programming to use the same name for a package and the names- 
pace that holds the code and data to implement the package’s functionality. The namespace export 
commands allow the entry points to be accessed (and namespace imported) by other programs. 

The pkg_mkIndex command will put only exported procedure names into the pkgIndex.tcl 
file. All procedures that can be called from code outside the package should be exported. Internal 
procedures should not be exported. 

If a namespace has internal variables that need to be initialized, define them using the vari - 
able command rather than the set command. This avoids potential confusion or limiting the use 
of namespaces that you might want to allow to be nested. 

All entry points should be visible from the top level of a namespace. If you implement a package 
as a set of nested namespaces and support direct access to the nested namespaces API, your top level 
namespace should import those procedures into the top level namespace. This technique allows the 
package developer to rework the package architecture without breaking application code that would 
otherwise have to understand the package’s internal structure. 

A procedure in a higher-level namespace can be invoked from a nested namespace as well as 
accessing procedures in a nested namespace from the higher level namespace. However, the procedure 
will need to be defined with a complete path. Tcl does not search up a tree of nested namespaces to 
find a procedure name. When Tcl evaluates a command, it tries first to evaluate the command in the 
requested namespace. If that fails, it attempts to evaluate the command in the global namespace. 

When info commands is evaluated in a nested namespace the output includes the commands in 
the current namespace scope and the global scope. It does not report commands in the higher level 
scopes. The info commands command reports only the procedures visible in the scope where the 
command is evaluated. 


8.7 BOTTOM LINE 

¢ Tcl namespaces can be used to hide procedures and data from the global scope. 

e One namespace can be nested within another. 

e The namespace commands manipulate the namespaces. 

e The namespace eval command evaluates its arguments within a particular namespace. 
Syntax: namespace eval namespaceID arg ?args? 

e The namespace export command makes its arguments visible outside the current namespace 
scope. 
Syntax: namespace export pattern ?patterns? 
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e The namespace import will make the procedures within a namespace local to the current 
namespace scope. 
Syntax: namespace import ?-force? ?pattern? 

e The namespace children command will list the children of a given namespace. 
Syntax: namespace children ?scope? ?pattern? 

e The namespace ensemble command allows scripts to be invoked as namespace command 
instead of namespace: : command. 
Syntax: namespace ensemble create -map{cmdName script} 

e The variable command declares a variable to be static within a namespace. The variable is not 
destroyed when procedures in the namespace scope complete processing. 
Syntax: variable varName ?value? ... ?varNameN? ?valueN? 

e Tcl libraries (packages) can be built from one or more files of Tcl scripts. 

e A module is a package that exists in a single file with a filename that conforms to the pattern 
NAME-REVISION. tm. 

e The package commands provide support for declaring what revision level of a package is provided 
and what revision level is required. 

e The package commands provide methods for manipulating packages. 

e The package provide command declares the name of a package being defined in a source file. 
Syntax: package provide packageName ?version? 

e The pkg_mkIndex command creates the pkgIndex.tcl file that lists the procedures defined in 
appropriate files. 
Syntax: pkg_mkIndex dir pattern ?pattern? 

e The package requires command declares what packages a script may require. 
Syntax: package require ?-exact? packageName ?versionNum? 


8.8 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under 
a minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e 100 What Tcl commands provide encapsulation functionality? 
e 101 What Tcl commands can be used to build an index of available procedures? 
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e 102 What Tcl commands support building modular programs? 

e 103 Can a Tcl namespace be used in a package? 

e 104 Can a Tcl namespace be nested within another namespace? 

¢ 105 What Tcl command is used to create a new namespace? 

e 106 Can more than one file be included in a package? 

e 107 What Tcl command will build a package index file? 

e 108 Can procedure names be imported from one namespace to another? 

e 109 Can a directory contain files that define multiple packages? 

e 110 Can a directory contain files that comprise multiple versions of a package? 

e {11 Can more than one file be included in a module? 

e 200 A FIFO queue can be implemented with a Tcl list. Create a queue namespace in which the 
Tcl list is a namespace variable. Implement push, pop, peek, and size procedures within the 
namespace. 

e 201 Make a queue package from the script developed in problem 200. Use the namespace 
ensemble command to allow the methods to be invoked as queue push, etc. instead of 
queue: :push. 

e 202 Given this code fragment: 
namespace eval pizza { 
variable toppingList 
variable size medium 
variable style deep-dish 
} 


Add procedures to 

a. Add toppings to a pizza. 

b. Set a pizza size. 

c. Set a pizza style. 

d. Report the size, style, and toppings on a pizza. 

e. Report the price of a pizza. (Define a base price and a price per topping. Ignore style and size.) 

e 203 Using the queue package from exercise 201, write a simulation of a single-queue check-out 
counter (such as a small grocery store). Each element pushed onto the queue will be an integer 
representing the time that this customer takes to be serviced. At each time interval, there will be a 
random chance that a new customer will be added to the queue. A good set of values for testing is 
a. Shortest Time: 2 sec 
b. Longest Time: 10 sec 
c. Customer Probability: .1 
Use a for loop to iterate through 1000 iterations, with each iteration representing 1 second of time 
in the simulation. At each iteration, record the size of the queue. Report the number of customers 
and the queue sizes. 

e 204 Expand the check-out counter simulation from exercise 203 to report how long each customer 
stands in line. You can do this by adding a second queue for customer wait times. Push the iteration 
when a customer is created onto the wait queue, and pop it when a customer is popped off the 
customer queue. 
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301] Expand the check-out counter simulation in exercise 204 to use 3 queues. Assume that a new 
customer always goes to the shortest queue. 

302 Modify the check-out counter simulation in exercise 301 to use 3 servers, but a single queue. 
303 Collect output from running the simulations built in exercise 301 and 302 and compare the wait 
time for N servers with N queues vs. N servers and 1 queue. 

304 Using the Tower of Hanoi board described in Section 8.1.7, write a script that will solve the 
puzzle. Information about the Tower of Hanoi puzzle is available at: 
www.dcs.napier.ac.uk/a.cumming/hanoi/ 

and www.cut-the-knot.com/recurrence/hanoi.shtml. 


CHAPTER 


Basic Object-Oriented 
Programming in Icl 


Over the years, Tcl has suffered from a surplus of object-oriented programming systems without ever 
having an object-oriented system integrated into the language. With Tcl8.6, the TclOO package has 
become part of the core language. TclOO can be used with Tcl8.5 as a loadable package. 

A few of the object-oriented packages that led to TclOO include: 


e Cincr tcl] 

This was the first object-oriented system for Tcl. Like C++, it has been a standard for many 
years. The [incr tcl] extension duplicates the C++ model of classes with single and multi- 
ple inheritance, friend classes, private, protected and public methods and both class and object 
variables. 

This is the most popular OO extension of Tcl. 

Initially, Lincr tcl] required changes to the Tcl kernel. After the addition of the namespace 
command, it became a loadable Tcl extension. The latest version of [incr tcl] is built using the 
8.6 TclOO package which this chapter introduces. 

e SNIT 

Snit (Snit Is not Incr Tcl) uses composition and delegation to define class relationships instead 
of the inheritance model used by C++ and Java. It is a pure-Tcl OO system (no compiled modules) 
and has been used to develop some megawidget libraries. 


e MIT Otcl 
A dynamic OO model that uses concepts from CLOS, Smalltalk and Self. 
e XOTcl 


The MIT Otcl project was extended and is now maintained as XOTcl (eXtended Otcl). XOTcl 
has a very rich set of functionality. It supports dynamic object-oriented programming with super 
classes for inheritance and mixins (at both class and object level) to further define sets of func- 
tionality. It supports assertions and filters to control code execution as well as other programming 
constructs. 

e TclOO 

TclOO was developed by Donal Fellows as a bare-bones OO system that could be used within 
Tcl to construct other OO systems. 

TclOO differs from other object-oriented packages in several ways: 

e TclOO is not intended to be a complete OO programming language. It is intended to be a base 
set of OO functionality that can be used to build a full-featured OO language. Despite this, it is 
very powerful, and useful for complex, real-world OO projects. 


Tcl/Tk: A Developer’s Guide. DOI: 10.1016/B978-0-12-384717-1.00009-9 24 1 
© 2012 Elsevier, Inc. All rights reserved. 
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TclOO was designed with support for the Tcl concepts of dynamic programming and introspec- 
tion built in. Many of the features developed for XOTcl were incorporated into TclOO. 

TclOO is part of the Tcl core, not an add-on package. It is always available to an application 
without requiring that a package be installed. 


This chapter will discuss how to use TclOO as a basic OO programming environment. The next 
chapter will discuss implementing more advanced features including class variables, class methods, 
introspection, runtime modifications of classes and individual object modification. 


CREATING A TCLOO CLASS AND OBJECT 


The TclOO commands are contained within the : :00:: namespace. This namespace contains several 
commands. Basic OO style programming only uses the 00: : class command, which is discussed in 
this chapter. The next chapters will cover the other oo: : commands. 

The ::00::class create command is used to create a new class. When a new class is cre- 
ated a new command with the same name as the class is also created to interact with the class. 
This is the same mechanism used by Tk to create commands to interact with widgets. 


Syntax: ::00::class create name script 
Define a new class 
name The name of the class being defined 
script A Tel script using TclOO commands to create a new class 


The script that defines a class is a normal Tcl script with the addition of a few commands that are 
specific to the class definition. The specific commands include: 


e method 
The method command creates a procedure (method) that can be evaluated within an object’s 
scope. 


Syntax: method name arguments body 
Define an object method 
name The name of the method being defined 


arguments The argument list for the method. All the usual procedure 
argument formats (default values, multiple arguments) are 
acceptable. 


body A Tel script to be evaluated when this method is invoked 


e constructor 
This creates a constructor for the class. This procedure will be called automatically when- 
ever an object of this class is created. This is the place to do initializations, define super classes, 
etc. The arguments to the constructor can be defined in all the styles supported by the proc 
command. 
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Syntax: constructor arguments body 
Initialize an object 


arguments The argument list for the method. All the usual procedure argument 
formats (default values, multiple arguments) are acceptable. 


body A Tel script to be evaluated when this method is invoked 


destructor 

The destructor method is invoked whenever an object is destroyed. If a class constructor allo- 
cates a scarce resource (for instance, a channel), it should be released in the destructor. Inherited 
objects will be destroyed automatically, but any aggregation objects created by the constructor or 
other methods should be destroyed in the destructor. 


Syntax: destructor body 
Cleanup when an object is destroyed. 
body A Tel script to be evaluated when this object is destroyed. 


variable 
This defines an object variable. The TcIOO variable command differs from the namespace 

variable command in these ways: 

e Variables within a class definition are not initialized using the variable command. They are 
initialized within the constructor. 

e The variable command can accept multiple variables on a single line, similar to the global 
command. 
In the 8.6 version of TclOO a variable command will replace any variables defined by a previ- 
ous variable command with the set of variables defined by the current variable command. 
This behavior is different from the namespace variable or global commands that simply 
add more variables to the list of variables. This behavior may change by the time 8.6 is out of 
beta. 


Syntax: variable variableNamel ?variableName2 ...? 
Declares the variables for an object. 
variableName... The list of variables. 


filter 

A filter method is evaluated before other object methods. A filter can be used to perform data 
validation, add debugging output, or other tasks that would otherwise need to be added to each 
method. A filter passes control to the originally requested method with the next command which 
will be discussed in more detail in the Method Chaining section. Evaluating the next command 
is similar to invoking a procedure. Control is passed to another method and then returns to the 
command after the next command. 

Any method in a class can be added to the filter stack. When an object’s method is invoked, the 
filter methods are invoked first. At each step, a filter method may evaluate a return, breaking the 
chain, or evaluate a next command, passing control to the next method in the chain. Evaluating 
the next command in the last method of a chain of filters passes control to the method that was 
originally requested. 
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The next command can be evaluated at any point in a filter method. For example, a filter might 
validate inputs and then pass control to the requested method with the next command, or it could 
pass control to the requested method first and then modify the returned values. 


Syntax: filter methodName 
Adds a method to the list of filters. 
methodName Name of a method to use as a filter. 
When a class is created with the 00::class create command, the Tcl interpreter creates a new 
command with the same name as the class. This new command has three subcommands: 
create Create a new object with a given name. The name of the new object is 
returned. 
new Create a new object with a computer-generated name. The name of the new 
object is returned. 
destroy Destroy the class and all objects of this class. 
Class methods can be invoked as 
objectName methodName arguments 


The following example defines a stack datastructure class. The stack is implemented as a Tcl list 
contained in an object variable named stackVar with two methods to access the list. The push method 
appends a new element to the end of the stack, and the pop method returns the last element from the 
stack. 

This script performs these actions: 


e a variable is created with the variable command. 
e apush method is created. 
¢ apop method is created. 


eee eee 
Example 1 


Creating a Class 


if Define the stack class 
if  stackVar: Contains the list of items in the stack 


::00::class create stack { 
variable stackVar ;# stackVar is a per—object variable. 


if The method to push data onto the top of a stack 


df 
if Arguments 
i## ~)©6 value A value to push onto the stack 


method push {value} { 
lappend stackVar $value 


} 


i## The method to pop data off the top of a stack 
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method pop {} { 
set rtn [Llindex $stackVar end] 
set stackVar [lrange $stackVar 0 end—1] 
return $rtn 


The next example shows how the stack class can be used. A new stack object named st is 
created, two strings are pushed onto the stack, and the last value onto the stack is popped off and 
displayed. 


eee 
Example 2 


Using a Class 


if Create a new object named ‘st’ 
stack create st 


i## Push values onto the ‘st’ stack 
st push "value 1" 
st push "value 2" 


i## Pop and display 
puts [st pop] 


Script Output 


value 2 


.1 Constructor and Destructor 


Many classes need some initialization when they are created. Any class that creates a resource in the 
constructor will probably need a destructor to release the resource when the class is destroyed. The 
resource could be an I/O channel, memory resources or other TclOO objects. 

Constructors and destructors are created in the class definition script. The definition of a construc- 
tor or destructor is similar to a procedure definition. A class may only have a single constructor or 
destructor. The constructor and destructor syntax resembles the method syntax except that no name is 
defined for the constructor or destructor. 


Syntax: constructor arguments body 
Constructor initializes an object when it is created. 
arguments The argument list for the method. All the usual procedure 
argument formats (default values, multiple arguments) are 
acceptable. 


body A Tcl script to be evaluated when this method is invoked 
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Syntax: destructor body 
Destructor cleans up when an object is destroyed. 
body A Tel script to be evaluated when this method is invoked 


This example shows how to create a class that writes to a file. The constructor accepts a filename 
to open, the write method sends data to the file, and the destructor will close the file. 


eee 
Example 3 


A Class with Constructor and Destructor 


00::class create logFile { 
variable channel 


if invoked when an object is created 
if Arguments 
i## ~=name The pathname of the log file to open 
constructor {name} { 
set channel [open $name w] 


} 


if invoked when an object is destroyed 
destructor { 
close $channel 


} 


if A method to send data to a channel 
if Arguments 
if data The text to write to the log file. 
method write {data} { 
puts $channel $data 


The next example shows how to use this class. When you create an object with a defined name 
(using the create subcommand) you provide the constructor arguments after the name of the new 
object, as is done with the Captain’s Log. When you create an object with an automatically generated 
name (using the new comamand), you only provide the constructor arguments, as is shown for the 
medical log. 


eee 
Example 4 


Using a Class with Constructor and Destructor 


logFile create captLog ./captLog.txt 
captLog write "Captain’s Log,Stardate [clock seconds ]" 
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captLog write "I wish something exciting would happen." 
captLog destroy 


set medicalLog [logFile new ./medLog.txt] 

$medicalLog write "The captain is showing signs of boredom" 
$medicalLog write "Initiating Kobyashi Maru scenario." 
$medicalLog destroy 


J 


~ 


.2 Methods 


A method is similar to a procedure with a few differences: 


e The method names are subcommands and do not show up with info commands or info procs. 
The name of a TclOO object is a command and will be displayed by info commands. Classes and 
objects can be examined with the info class and info object commands, which are discussed 
in the next chapter. 

e A method has access to all the variables associated with the object as well as global scope variables. 


TclOO methods behave similar to procedures in these respects: 


e A TclOO class may have as many methods as it needs. The only limit is system resources. 

e An object’s method may be registered as the callback script to be evaluated when an event occurs 
via the after or fileevent commands, or as a widget callback. 

e An object may invoke its own methods, or the methods from other objects within a method. 


Method Naming Convention 

Any word that is valid for a Tcl command or procedure name can be used within a class as a method 
name. You can even re-use global scope command and procedure names as method names. Re-using 
command or procedure names as method names is not recommended—it will work, but is prone to 
unexplained bugs if you accidentally invoke the command instead of the method. 

The Tc] Engineering Guide recommends that procedures within a namespace use a naming con- 
vention in which procedures that start with a lower-case letter are part of the public API and may be 
exported, while names that start with an upper-case letter are for internal use only. 

The TclOO package adheres to this convention. 

The next example shows methods defined with one publicly available method (show) and one 
internal method (Hi ddenShow). 

Notice that the error message reports that there are two available methods, show and destroy. 
TclOO automatically creates a destroy method for all objects. 


Se 
Example 5 


Defining and Using Methods 


00::class create methods { 
variable varl var2 
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constructor {vall val2} { 
set varl $vall 
set var2 $val2 


} 


method show {} { 
puts "Show: VAR1: $varl VAR2: $var2" 


} 


method HiddenShow {} { 
puts "“HiddenShow: VARI: $varl VAR2: $var2" 


} 
} 


methods create ml 2 
m show 
m HiddenShow 


Script Output 


Show: VAR1: 1 VAR2: 2 
unknown method "HiddenShow": must be destroy or show 


| 
Invoking Methods from Within Methods 


Any existing command, procedure or object method can be evaluated within the body of a method. As 
you would expect, if you attempt to evaluate a procedure or an object method that has not yet been 
defined, the Tcl interpreter will generate an error. 

Note that methods are not commands. When an object is instantiated, the object name is used as 
the name of a command, and the methods are subcommands within that command. This is expanded 
from the namespace ensemble command discussed in Chapter 8. 

You can invoke methods for other objects with the name of the object and the method name, just as 
you would evaluate an object’s method from the global or a procedure scope. 

In order to evaluate a method within the current object, TclOO provides the virtual command my. 
Each object has a my command that is the current object. 

In the next example a class is created with three methods to show evaluating the objects methods. 


showValue Displays the value of the object variable. 
external Invokes the showValue method of another object. 
internal Invokes the showValue method of the current object. 


eee 
Example 6 


Evaluating Object Methods 


00::class create hasMethods { 
variable value 
constructor {val} { 
set value $val 
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} 

method showValue {} { 
puts "Value is: $value" 
} 
method external {objName} { 
objName showValue 

} 
method internal {} { 
y showValue 


} 


set obl [LhasMethods new 1] 
set ob2 [LhasMethods new 2] 


$ob1 external $o0b2 
$obl1 internal 


Script Output 


Value is: 2 
Value is: 1 


If your code tries to invoke a method with just the method name, it will either fail (because the 
command is undefined) or it will evaluate a command or procedure defined in the global scope. It is 
good policy to not overload the names of global scope commands within a class. 

The next example shows the unexpected consequences of overusing a command that already exists 
in the Tcl interpreter. 


ooo —_—nmnmn— —Owm!~ 
Example 7 


Evaluating Object Methods 
00::class create methodDemo { 


variable a bc 
constructor {} { 


setal 
set b 2 
set c 3 


} 
method puts {var} { 
puts "THE VALUE of $var IS: [set $var]" 


method bad_showContents {} { 
puts a 
puts b 
puts c 


250 CHAPTER 9 Basic Object-Oriented Programming in Tcl 


method good_showContents {} { 
my puts a 
my puts b 
my puts c 
} 
} 


methodDemo create demo 


puts " BAD:" 

demo bad_-showContents 

puts "GOOD:" 

demo good_showContents 
Script Output 

BAD: 

a 

GOOD: 


THE VALUE of a IS: 1 
THE VALUE of b IS: 2 
THE VALUE of c IS: 3 


| 
Registering Methods for Callbacks 


Several Tcl/Tk mechanisms are implemented via a callback. Some examples are the af ter command, 
fileevents and commands associated with a Tk button. These commands need to include the object 
as well as the method in order to be evaluated in the correct scope. 

The Tcl namespace package includes the namespace current command in order to register 
a namespace procedure with a callback. The namespace current command returns the current 
namespace, which can be combined with a procedure name to provide a complete path to the procedure. 

TclOO has a se1 f command that returns the name of the current object. This name can be combined 
with the method name and any arguments to register a callback. 

This example shows the after command being used both inside and outside an object. Notice that 
the after10 method uses the sel f command while the global scope uses the name of the object. If 
you try using this code in an interactive test, run it inside the wish shell, rather than tclsh, in order for 
the event loop to be evaluated. 


oOo ——_ nn — gy: = 
Example 8 


Registering Object Methods as Callbacks 


00::class create delayed { 
variable x 
constructor {val} { 
set x $val 


} 
method show {} { 
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puts "SHOW: x is $x at [clock seconds]" 


} 
method afterl0 {} { 
after 10000 [list [self] show] 


} 


set a [delayed new 2] 

set b [delayed new 4] 

$a afterl0d 

after 5000 [list $b show] 


Script Output 


SHOW: x is 4 at 1295761965 
SHOW: x is 2 at 1295761970 


Your code may use either my or [sel f ] when invoking object methods from within an object method. 
Only [self] can be used when registering a callback, since the my command only exists within the 
scope where code is currently being evaluated. 


9.1.3 Inheritance 

One of the driving forces in object-oriented design and programming is the ability to re-use and extend 
code. The term for adding new functionality from another class is inheritance. The many object 
oriented languages all have slightly different models for inheriting variables and methods from other 
classes. 

TclOO supports single inheritance, multiple inheritance and mixins as methods for merging the 
functionality of multiple classes into a single class. There are different reasons for using each style of 
inheritance, and slightly different behaviors. 

Single inheritance is suitable when you have several classes that will share some functionality but 
have additional parameters or methods that must be implemented differently. For example, a business 
might have a base class personne? with derived classes for salaried staff and hourly staff. 

Multiple inheritance is suitable when the derived classes have permanent parameters and methods 
from other classes. In the business example, an hourly union worker might inherit from both the hourly 
worker and union classes. 

Mixins are frequently a better choice than multiple inheritance. A mixin is most appropriate when 
a class has special features that are orthogonal to the inheritance lineage. For instance, a photo of the 
employee is not related to employee’s paycheck and might be part of a biographical mixin. 

The next chapter will discuss how mixins can be added on a per-object basis, which makes it easy to 
build custom objects without needing a large, pre-defined class hierarchy that covers all possible com- 
binations. Using per-object mixins we could add individual employee skills, adding welding methods 
to one employee and accounting methods to another. 
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Method Chaining 

In order to create a uniform API, multiple classes will need to use the same name for a method. For 
example, a method in a derived class might pre-process data into a standard form and then pass control 
to a method with the same name in a superclass. 

It’s quite common for the same method name to be used in a class, one or more superclasses, and 
even one or more mixins. This can create a problem in determining which methods will be invoked 
and which order they’!] be invoked in. 

TclOO constructs a method chain to define the order in which methods will be invoked. Within a 
method, control can be transferred to the next method in the stack with the next command. 


Syntax: next args 
Invoke the next method in a hierarchy. 


args alist of arguments to be passed to the next method. 


For simple class hierarchies the method chain is built in the order shown below. This will be 
expanded in the next chapter after more complex hierarchies are discussed. If a method can appear 
in the chain more than once (perhaps a class has been included both as a super and a mixin), it will be 
added at the latest valid position. 


Filter Methods If multiple filters are associated with a class, they appear in the order of the class 
hierarchy. 

Mixin Methods A method from a mixin is evaluated next. If there are multiple mixins, they are 
added in the order they are defined in the list of mixins. 

Class Methods A method defined in the class description text is evaluated next. 

Superclass Methods Methods from the superclasses are added in the order that the superclasses 
were defined. If the superclasses include more superclasses, those methods will be added before 
proceeding to the next superclass. 


The next command can define the arguments being passed to the next method. It always invokes 
the next method in the method chain. It can’t skip methods and cannot specify which overridden 
method to invoke (the next chapters will discuss doing tricky stuff with the method chain.) 

The return from next is whatever value the first method in the chain returns. If the return value 
from an interior method needs to be returned, the code will have to propagate that value. 

The next command can be used at any point in a method, filter, constructor or destructor. This 
gives the script author the ability to both rework arguments before passing them to a superclass and 
rework results before they are returned from the object. 


Inheritance 

The next few examples will develop a small class hierarchy to define a character in a fantasy game. A 
character in a fantasy game has a name and a few attributes like how well it can defend itself, how well 
it attacks and how many life points it has. 

This base class can be modified in several ways. The values of the parameters can be changed 
permanently based on the character’s race (human, elf, dwarf, etc.) and occupation (knight, wizard, 
healer, etc.). The character’s abilities can also be modified temporarily when the character uses artifacts 
such as magic armor and weapons. 
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Most of the methods in these classes have puts commands to make it easy to show the call 
hierarchy as they are invoked. 


—_———— rs sore 
Example 9 


Base Character Class 


if Define a base character class with the default values 
i## for defensive strength, attack strength and life points 


00::class create character { 
variable state 


## Constructor assigns base values 


constructor {name} { 
puts "character constructor" 
array set state {defense 2 attack 3 hitpoints 5} 
set State{name} $name 


} 
## Display the values for debugging 


method show {} { 
parray State 
} 


# Return whether an attack is larger than the character’s 
i## defensive ability 


method defense {attackStrength} { 

puts "Final Attack is: $attackStrength" 

if {$attackStrength > $State(defense)} { 

return " $attackStrength is larger than $State(defense) ,\ 

$State(name) is Hit" 
} else { 

return " $attackStrength is not larger than $State(defense) ,\ 

$State(name) is Missed" 


Single Inheritance 

Single inheritance is the simplest of the inheritance models. This is used when you have a class that 
has basic characteristics and you need to create more classes that have all the basic characteristics and 
some specific characteristics. 
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One way of defining characters in a Fantasy boardgame is to start with a base set of parameters, 
and then modify them depending on the character’s class (Warrior, Mage, etc.) 

The next example uses the character class as a basis for a warrior class. A warrior character 
has higher attack and defense skills, so these values are modified in the constructor. 

In the warrior constructor, the attack and defense are modified after the next command is 
invoked. This allows the character class to set the initial values before they are changed. 

Also notice that the name parameter must be provided to the character class using the next 
command, since the name is assigned in that class. 


——— ee OO 
Example 10 


Single Inheritance 


source character.tcl 


i## Define a warrior that has better attack and defense 
if skills because of its class 


00::class create warrior { 
superclass character 
variable State 
constructor {name} { 
puts “warrior constructor" 
next $name 
incr State(defense) 2 
incr State(attack) 2 


} 
} 

puts "Create object" 
warrior create elmer siegfried 
puts "" 
puts "Show object" 
elmer show 
puts "" 
puts "Attack value 8 against a warrior" 
puts Lelmer defense 8] 

Script Output 


Create object 
Warrior constructor 
Character constructor 


Show object 


State (attack) =4 
State (defense) =4 
State(hitpoints) = 5 
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State (name) = Siegfried 


Attack value 8 against a warrior 
Final Attack is: 8 
8 is larger than 4, Siegfried is Hit 


Multiple Inheritance 

Some class hierarchies will require that a class inherit characteristics from more than one parent class. 
This can be done by using multiple parent classes as arguments to the superclass. Do not use mul- 
tiple superclass commands—as with the TclOO variable command, the latter commands overwrite 
the previous ones. (This behavior may change when Tcl8.6 is fully released.) 

Multiple inheritance should only be used if there is a reason in the class logic to use multiple 
inheritance. With languages like C++, multiple inheritance is used to add functionality that might not 
be part of the logical class relationships. For example, a C++ class might use multiple inheritance 
to include both calculation methods and GUI graphing methods. In TclOO, adding features that are 
orthogonal to the class logic should be done with the mi xin command, which will be discussed in the 
next section. 

A fantasy character can have characteristics modified based on both race and occupation. For this 
example, our hero has better defense and attack values because he is a warrior, and more hitpoints 
because he is a human. 

In this example, each constructor displays when it is invoked. The constructors are placed in the 
call tree in the order that they appear in the super command. The next command steps to the next 
procedure in the call tree. 


ooo.” nn ae -e 
Example 11 


Multiple Inheritance 


source character.tcl 


00::class create warrior { 
variable State 
constructor {name} { 
puts "Warrior constructor 
next $name 
incr State(defense) 2 
incr State(attack) 2 


00::class create human { 
variable State 
constructor {name} { 
puts "Human constructor" 
next $name 
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incr State(hitpoints) 2 


00::class create humanwarrior { 
superclass human warrior character 
variable State 
constructor {name} { 
puts "Human Warrior constructor" 
next $name 


puts "Creating a human warrior" 
humanwarrior create elmer Sigfried 
outs 

ts "The character’s attributes are:" 
elmer show 

outs "" 

puts "Attack value 8 with no armor" 
puts Lelmer defense 8] 


Script Output 


Creating a human warrior 
Human Warrior constructor 
Human constructor 
Warrior constructor 
Character constructor 


The character’s attributes are: 


State (attack) =4 
State (defense) =4 
State (hitpoints) = 7 
State (name) = Sigfried 


Attack value 8 with no armor 
Final Attack is: 8 
8 is larger than 4, Sigfried is Hit 


Using Mixins 

Mixins are useful for parameters and methods that are orthogonal to the class logic or are likely to 
change. For instance, a mixin is a better choice than multiple inheritance for adding a GUI to a class 
that does data analysis. 
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Our fantasy hero will need weapons and armor. These could be added by having the class inherit 
a dagger and shield, but possessions are different from base attributes like strength. Using inheritance 
for this makes the logic of defining the character muddy. 

The next example shows how we can use mixins to add a dagger and shield. For this example, 
we’re only worrying about our hero’s ability to defend himself. A real class would include an attack 
method as well. 

One feature of mixins is that they are designed to be added and removed at creation time or runtime. 
The next chapter will show how to handle the character finding better armor and weapons. 


Oooo nnn Oe y-Em 
Example 12 


Multiple Inheritance 


source character.tcl 


00::class create warrior { 
variable State 
constructor {name} { 
puts "Warrior constructor" 
next $name 
incr State(defense) 2 
incr State(attack) 2 


} 


00::class create human { 
variable State 
constructor {name} { 
puts "Human constructor" 
next $name 
incr State(hitpoints) 2 


} 


00::class create shield { 
method defense {attackStrength} { 
puts "Shield reduces attack by 2" 
return [next [expr {$attackStrength — 2}]] 


} 


00::class create dagger { 
method defense {attackStrength} { 
puts "Dagger reduces attack by 1" 
return [next [expr {$attackStrength — 1}]] 
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00::class create humanwarrior { 
superclass human warrior character 
mixin shield dagger 
variable State 
constructor {name} { 
puts “Human Warrior constructor" 
next $name 


humanwarrior create elmer Sigfried 
puts "™" 
puts "The characters attributes are:" 
elmer show 


puts "" 
puts "Attack value 8 against human warrior with dagger and shield" 
puts Lelmer defense 8] 


Script Output 


Human Warrior constructor 
Human constructor 
Warrior constructor 
Character constructor 


The characters attributes are: 


State (attack) =4 
State (defense) =4 
State(hitpoints) = 7 
State (name) = Sigfried 


Attack value 8 against human warrior with dagger and shield 
Shield reduces attack by 2 
Dagger reduces attack by 1 
Final Attack is: 5 
5 is larger than 4, Sigfried is Hit 


| 
Aggregation 


The superclass and mixin define the is-a relationship that objects can have—a warrior is a character. 
An object can also have a has-a relationship to other objects. For instance, our character may have one 
or more treasures. 

The has-a relationship can be implemented as a Tcl list of object identifiers. Object methods can be 
invoked by methods in other objects just as the methods are invoked from mainline code. 
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The next example shows a character with an acquire method. The character’s possessions are a 
list of treasure objects (00::0bj6 and 00::0bj/). The acquire method simply appends the new 
object to the list of possessions. 

The netWorth method steps through the objects, invokes each object’s getValue method, and 
calculates the total value of the treasure. 


OOOO” —nnn— g_ 
Example 13 


Multiple Inheritance 


if Define the character class 
00::class create character { 
variable State 


## This character has a name and a list of possessions 
constructor {nm} { 

set State(name) $nm 

set State(possessions) {} 


} 


i## Display the contents of the State variable 
method show {} { 

parray State 
} 


i Acquire a new item by appending it to 
# the list of possessions 
method acquire {item} { 

lappend State(possessions) $item 


} 


## Return the total value of the treasures 
method netWorth {} { 
set total 0 
foreach item $State(possessions) { 
incr total [$item getValue] 


return $total 


if Define a treasure class 
00::class create treasure { 


i## Treasures have a name and a value 
variable name value 


constructor {nm val} { 
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set name $nm 
set value $val 


} 


jf Return the value of this treasure 
method getValue {} { 
return $value 
} 
} 


if Create a character and create two treasures 
i## that the character has acquired. 

character create daffy Allmine 

daffy acquire [treasure new ruby 100] 

daffy acquire [treasure new diamond 200] 


puts "Daffy’s State is:" 
daffy show 
puts "Allmine has treasure worth: [daffy netWorth]" 


Script Output 


Daffy’s State is: 

State (name) Allmine 

State (possessions) = ::00::Obj6 ::00::Obj7 
Allmine has treasure worth: 300 


|_| 
9.1.4 Filters 


There are some actions that need to be evaluated in each of a class’s methods. These actions may 
include input validation, logging, displaying debugging information, etc. The fi1ter command lets 
you define one or more methods to be called before evaluating an object’s methods. The filter can 
either abort processing with a return command, or pass control to the next method with the next 
command. 

A filter is invoked before a method or destructor is evaluated, but is not evaluated before a 
constructor. 

A filter is defined as part of the 00::class create command, similar to the way that superclasses 
and variables are defined. 


Syntax: filter methodName 
Adds a method to the list of filters. 


methodName Name of a method to use as a filter. 


The next example shows how to use a filter to test inputs before calling an object’s methods. 
The rectangle class has no constructor, just a method to calculate a rectangle’s area and the fil- 
ter. The filter will abort processing and return an area of 0 if the height or width of a rectangle are less 
than 0. 
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eee 
Example 14 


Filter to Test Inputs 


00::class create rectangle { 
filter isPositive 


## Check that height and width are both positive. 
method isPositive {ht wd} { 
if {($ht < 0) || ($wd < 0)} { 
return 0 
} else { 
next $ht $wd 
} 


} 


if Calculate the area of a rectangle of given height and width. 
method area {ht wd} { 
return Lexpr {$ht *« $wd}] 
} 
} 


rectangle create rl 
puts "Area of a 2 x 3 rectangle is: [rl area 2 3]" 
puts "Area of a 2 x —3 rectangle is: [rl area 2 —3]" 


Script Output 


Area of a 2 x 3 rectangle is: 6 
Area of a 2 x —3 rectangle is: 0 


A filter method does not need to be a defined part of a class. The method may be defined in a mixin 
or as part of a superclass. When debugging a problem, sometimes it’s useful to display information 
whenever any method is invoked. 

The next example is a small debug class with a single method to display the object name, method 
being evaluated and the arguments. The showCal1 method uses the info command to display the 
contents. The filter is being evaluated as part of invoking the object’s method, so the info level 
command uses a relative position of 0 in the procedure stack to show the information. 


——_—,r,,r,_ee_a«reEEoEoeeeeeeeeeeee 
Example 15 


Filter to Provide Debug Info 
00::class create debug { 
method showCall {args} { 
puts "——— Debugging: [info level 0]" 
next {x}$args 
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The debug class can be mixed into another class to provide debugging information while the code is 
being developed, and then removed once the code is perfect. 

The next example shows the previous humanwarrior class with the debugging information added. 
Whenever one of the e] mer methods is invoked, the showCal1 method displays the object, method 
name and arguments. 
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Example 16 


Using a Mixin Filter 


source character.tcl 
source debug.tcl 


00::class create warrior { 
if Mix in the debug class and add the filter 
mixin debug 
filter showCall 


variable State 
constructor {name} { 
puts "Warrior constructor" 
next $name 
incr State(defense) 2 
incr State(attack) 2 


} 


00::class create human { 
variable State 
constructor {name} { 
puts “Human constructor" 
next $name 
incr State(hitpoints) 2 


} 


00::class create humanwarrior { 
superclass human warrior character 
variable State 
constructor {name} { 
puts "Human Warrior constructor" 
next $name 


} 
humanwarrior create elmer Sigfried 


elmer show 
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puts "Attack value 8 against human warrior" 
puts Lelmer defense 8] 


Script Output 


Human Warrior constructor 
Human constructor 

Warrior constructor 
Character constructor 

—— Debugging: elmer show 
State (attack) =4 

State (defense) 4 
State(hitpoints) = 7 

State (name) = Sigfried 


Attack value 8 against human warrior 
—— Debugging: elmer defense 8 
Final Attack is: 8 

8 is larger than 4, Sigfried is Hit 


Using the filter for debugging like this is better than adding a lot of code to each method to track a 
class’s behavior, but it would be nicer if this class could be mixed in at run time, or on a single object. 
These techniques will be discussed in the next chapter. 


BOTTOM LINE 


e Tcl supports several object systems. The most popular have been [incr tcl], XOTcl and SNIT. 

e The TclOO package is built in with Tcl 8.6 and newer. 

e The TclOO package is available as a loadable package for Tcl 8.5. 

e The TclOO package is designed to be a minimal OO package that can also be used as a basis for 
creating more complex OO packages. 

e TclOO supports single inheritance, multiple inheritance, mixins and method chaining. 

e The TclOO commands are created in the : : 00: : namespace. 

e A new class is defined with the ::00::class create command. 


Syntax: ::00::class create name script 
Define a new class 


name The name of the class being defined 
script A Tcl script using TclOO commands to create a new class 


e Acclass may contain a constructor, a destructor and multiple variables, methods, superclasses and 
mixin classes. 

e The next command passes control to the next method in a method chain. 

e A filter method will be invoked before other object methods. The filter may abort processing the 
method or pass control to other methods in the call chain. The filter may modify inputs before 
passing control to the next layer and may modify return values before returning control to the 
calling code. 
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9.3 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under 
a minute to answer. 


200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


¢ 100 What Tcl command will define a new class? 

e 101 How many constructors can a class possess? 

e 102 Cana Tcl class have more than one method? 

e 103 What does the next command return? 

e 104 When is a constructor called? 

e 105 What command is used to inherit characteristics from another class? 


e 106 What command should be used to inherit methods that are not part of a class’s logical 
construction (for instance, a set of debugging methods)? 


e 107 What command can be added to a class definition to preprocess arguments before any method 
is evaluated? 


e 200 Expand the stack class described in this chapter by adding methods for peek and size. 


e 201 Define a card class for playing cards. The class should have a parameter for suit (clubs, 
spades, etc.), name (Ace, King, Queen, etc.) and value (Ace might be 14, King would be 13, 
Queen would be 12, etc.). 


e 202 Add a method to the card class from exercise 201 to return a card’s rank. 


e 203 Add a method to the card class from exercise 202 to compare the current to the value of a 
card object passed as an argument. Using this method to compare a King and Ace might look like 
this: 

set cardl [card create Ace Spades] 
set card2 [card create King Diamonds ] 
$cardl compare $card2 

Larger 
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$card2 compare $cardl 
Smaller 


204 A Pizza namespace was created in Chapter 8, exercise 202. Write a TclOO class with the same 
variables and methods. 


300 Define a deck of cards class that inherits from the stack class in exercise 201 and the card 
class from 204. The deck class will need a destructor to destroy the cards when a deck is 
destroyed. 


301 Add a shuffle method to the deck of cards class created for exercise 300. 


302 Write an application to play a game of war against the computer. This will need a deck of 
cards class and four stack classes (one for the played cards and one for unplayed cards for both the 
user and the computer). Use the compare method from exercise 203 to determine which player 
wins each round and then push the cards onto the appropriate stack. 


303 Add an attack method to the humanwarrior class described in this chapter. There will need 
to be attack methods in the base character class and the weapon class. The final value returned 
should be calculated from the character’s base attack value, the character’s weapon and a random 
value. 


304 Add a method to calculate the damage inflicted by a weapon. This should be added to a 
weapon class. 


305 Add a method to accept the damage inflicted by a weapon. This should be added to the 
character class. 


CHAPTER 


Advanced Object-Oriented 
Programming in Icl 


There are many styles of object programming languages, ranging from the dynamically configured 
Smalltalk-like languages to the rigidly defined Java and C++ style languages. 

One goal of the TclOO package is to allow the programmer to use whatever features they need 
to develop their application and to provide object-oriented programming support in a form that’s 
consistent with the rest of Tcl, being both dynamic and introspective. 

TclOO can be used like C++ or Java with a set of classes and inheritance defined during a project’s 
design phase. You can also use TclOO in a dynamic manner, with classes and objects being defined 
while an application is running. TclOO classes and objects can be modified at runtime: new methods 
can be added or modified, variables can be added or deleted, mixins can be added or removed, and 
even inheritance can be modified. 

This is very different from the C++/Java view of OO programming as unchanging class structures 
and methods. The dynamic nature of the TclOO classes and objects gives the developer powerful tools 
to develop applications that run in changing environments. 

The flip side of the dynamic nature of TclOO is the introspective nature. As with other Tcl 
applications, you can examine an object to discover its class, superclasses, mixins, variables, etc. 

Tcl’s introspection support is a different technique than the black-box design paradigm of the C++ 
and Java style languages. You can program using the paradigm that an object’s state is hidden, or you 
can use the Tcl introspection tools to examine an object’s state. 

This is a powerful tool during debugging and also makes it easy to write generic functions to 
serialize a class or object in order to completely save and restore an application’s state. 

The dynamic and introspective nature of TclOO are powerful tools. Using these tools can make 
complex tasks easier and can also allow a careless programmer to write code that is difficult to maintain. 
When functionality can be created easily with traditional OO methods, it’s best to stick to the minimal 
set of functionality. However, when the going gets tough, TclOO has the tools to deal with the unusual 
programming environments. 

The commands that implement these features are: 


oo::define Define a feature for all members of a class. 

00o::objdefine Define a feature for a single object. 

info class Return information about a class. 

info object Return information about a single object. 

The 00::class commands introduced in the previous chapter provide the basic inheritance and 


mixin styles of object-oriented programming. This chapter introduces more commands that provide the 
developer with more capabilities and dig deeper into the underlying structure of TclOO. 
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10.1 MODIFYING CLASSES AND OBJECTS 


The dynamic nature of TclOO means that a Tcl application can adapt to a changing environment 
without the developer needing to know all the possible permutations at design time. 

We can use the ability to redefine a class’s behavior to model real world systems better. For instance, 
a simulation of elevators in an office needs to define what an elevator does when it has no active request. 
The default behavior for an idle elevator might be to wait at the last floor it was sent to until there is a 
request from another floor. During the morning rush, you might want an idle elevator to return to the 
main floor to be immediately available for folks coming to work. 

Rather than clutter an idle method with information about time of day, we can use the 
oo::define command to change the id1e method depending on the time of day. 

We can use the 00: :objdefine command to modify the behavior of a single object, rather than 
all objects of a class. We could use this to make one elevator an express that only runs from the main 
floor to the floor where most people work during the morning and afternoon rush times. 


10.1.1 Modifying Classes 

The 00::define command defines features that will be common to all members of a class. Most 
class attributes are defined using the 00::class command. The 00::class command invokes the 
o0o::define command to fulfill these parameter requests. 

The 00::define command is also available at the script level, which allows an application to 
customize a class or define features like static class methods that are not supported by the 00: :class 
command. 

The 00::define command supports all of the features that can be defined in an 00::class 
create script. This provides the potential for reworking a class at runtime, as well as defining it 
during the design phase of a project. 

When 00: : define is used to change a feature of a class that has objects, all the existing objects 
immediately gain the new feature and all new objects are built with the new features. 

Like other Tcl commands, the 00::define command supports several sub-commands. It also 
supports two argument conventions as shown in the next table. 


e asingle subcommand and required arguments. 
¢ ascript which might contain several subcommands to evaluate 


Syntax: 00::define className script 
00::define className ?subcommand ?argl arg2 ...? 
Define a feature of a class. 


className The name of the class to be modified. 


script A script with commands to modify the class. 
This may modify several features. 


subcommand A subcommand that defines a single feature 
to be modified. 


?argl arg2 ...? Thearguments that a subcommand requires. 
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All of the commands to modify a class are supported in both the script and subcommand version 
of the 00: :define command. 


Modifying Methods 

¢ Creating or modifying a method 
A new method can be added to an existing class or a method body can be changed with the method 
command. After this command is evaluated, all existing objects of this class as well as all newly 
created objects will contain the new method. 


Syntax: oo::define className method methodName arguments script 
Define a new method for all members of a class. 
methodName The name of the method to be added. 


arguments A list of method arguments, following the 
normal Tcl procedure argument format. 


script The body to be evaluated when the method is 
invoked. 


## Create an addition class 
00::class create addition { 
} 


i## Add a method to the addition class 

00::define addition method add {a b} { 
return [expr {$a + $b}] 

} 


e Adding a filter to a class 
A filter method is one that will be called before other class methods. This can be used to check 
inputs before passing control to the requested method with the next command or to modify results 
after the next command has been evaluated. A filter can also be used as a debugging tool to display 
information when methods are invoked or to capture method calls during early development when 
the methods are not yet implemented. 

A filter method can be used to redirect processing if a system has a systemic failure. For exam- 
ple, if a connection to a remote database server fails, a filter can be used to redirect calls to the 
database object methods to create a journal that can be used to update the database when the 
connectivity is restored. 

A permanent filter to check method inputs should be defined in the 00::class create defi- 
nition. A temporary filter for use during development, debugging or to handle exception states can 
be defined with the fi 1 ter subcommand. 

A filter must be a method in a class that’s included in the class hierarchy. It can be a method in a 
mixin or inherited class. A filter cannot be a normal Tcl procedure. If you attempt to add an illegal 
method to the filter list it will not be added. 


Syntax: oo::define className filter methodName ?methodName? 
Add one or more methods to the list of filters for all members of a class. 


methodName The name of the method to be added to the 
filter list. 


SSS) 
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if Define a new method to show information about a method call] 
00::define addition method show {args} { 

puts "--- [info level 0]" 

next {x}$args 
} 


dt Show method information before all method calls 
if to addition objects 
00::define addition filter show 


Forwarding one method to another 
In order to migrate code from one set of libraries to another it’s sometimes easier to rework the 
library, rather than rework all the original code. You can use the forward subcommand to create 
an alias for a method by mapping one method name to another or even to a normal Tcl procedure. 
Forwarding a method is a one-way street. When a method call is forwarded the Tcl call stack 
is modified to show the location that has been forwarded to, not the original method call. There is 
no information available within the forwarded procedure to redirect evaluation back to the original 
method. 


Syntax: oo::define className forward newName actualCmd ?args? 
Forward an invocation of newName to actualCmd with 


optional arguments added before the arguments provided 
to newName. 


newName The name of a new method for this class. 


actualCmd Thecommand to evaluate when the newName 
method is invoked. 


?args? Arguments which will be placed before any 
arguments in the invocation of newName. 


it Add a forward to a global scope procedure 
oo::define addition forward print puts 


if Add a ‘sum’ method by re-using the ‘add’ method. 

00::define addition forward sum my add 
Renaming a method 
If you are using class libraries from several sources you may run into method name conflicts. TclOO 
creates a method chain of methods in superclasses and mixins by name. If multiple classes have 
methods with the same name all these methods will be added to the method chain. If you need to 
remove a method from the chain, you can rename it. 


Syntax: oo::define className renamemethod oldName newName 
Renames a method. 
oldName The current name for this method. 


newName The new name for this method. 


if Rename the sum2 method to twice 
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o00::define addition renamemethod sum2 twice 


puts "Renamed to twice: [LaddObj twice 1 2]\n" 


Renaming a method will not modify code that relies on the old method name. This includes filters 
and forwards as well as code inside a method that invokes another method. 
The example below will fail. 


eee 
Example 1 
Script Example 


if Add a ‘sum’ method by re-using the ‘add’ method. 
00::define addition forward sum my add 


if Rename the add method 
00::define addition renamemethod add oldAdd 


addObj sum 3 4 


Script Output 


# Error: unknown method "add". 


e Deleting a method 
If you have added a method for temporary use, you will need to delete it when the need is gone. 
The deletemethod subcommand removes a method from a class and all of that class’s objects. 
If the method is referenced in other evaluation lists (fi 1] ter or forward), it is removed from those 
lists also. 


Syntax: oo::define className deletemethod methodName ?methodName? 
Delete a method from all members of a class. 


methodName The name of the method to be deleted. 


i## Done with debugging now, delete filter method 
00::define addition deletemethod show 


e Private and public methods 
The preferred coding style for using Tcl namespaces is to name public procedures with lower- 
case letters and private procedures with uppercase letters. This is just a convention with the Tcl 
namespace. TclOO enforces this convention. 

Like most restrictions in Tcl, we can work around it. 

The export and unexport commands can be used to export a method that starts with an 
uppercase letter, or to unexport one that starts with a lowercase letter. You can use these commands 
within a class definition as you would use public and private in C++ or Java, or you can modify 
the class at runtime with the 00: :define command. 
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Both exported and unexported methods are available to derived classes and when a class with a 
private method is mixed into another class. 


Syntax: 


Syntax: 


oo::define className export methodName ?methodName? 


Make a method available at the global scope. 


methodName The name of the method to be made public. 


oo::define className unexport methodName ?methodName? 
Make a method unavailable at the global scope. 


methodName The name of the method to be made private. 


$$$ $a 


Example 2 


Script Example 

00::class create hasPrivateMethod { 
method PrivateMethod {args} { 
puts "PrivateMethod $args" 


} 
} 


00::class create usesPrivateMethod { 
superclass hasPrivateMethod 


method usePrivateMethod {args} { 
my PrivateMethod "From usesPrivateMethod $args" 


} 


hasPrivateMethod create privatel 
usesPrivateMethod create usel 


puts "\n—— de 
usel usePrivateMethod "from global scope" 
catch {private 
puts "Attempt 


puts "\n— af 
oo: :defi 


fault state" 


PrivateMethod "from global"} rtn 
to access PrivateMethod returns:\n $rtn" 


ter export" 


ne hasPrivateMethod export PrivateMethod 


privatel Priva 
puts "\n— af 
00::defi 


teMethod "from global after export" 


ter unexport" 


ne hasPrivateMethod unexport PrivateMethod 


catch {private 
puts "Attempt 


PrivateMethod "from global after unexport"} rtn 
to access PrivateMethod returns:\n $rtn" 


usel usePrivateMethod "from global scope" 
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Script Output 
—— default state 
PrivateMethod {From usesPrivateMethod {from global scope}} 
Attempt to access PrivateMethod returns: 
unknown method "PrivateMethod": must be destroy 


—— after export 
PrivateMethod {from global after export} 


—— after unexport 

Attempt to access PrivateMethod returns: 

unknown method "PrivateMethod": must be destroy 
PrivateMethod {From usesPrivateMethod {from global scope}} 


The example below demonstrates the commands that create and modify methods. The addition class 
is created with no methods. Methods are added as they are needed with the 00::define className 
method command. 


ec EEE 
Example 3 
Using method, filter, forward and deletemethod 

# Create an addition class 

00::class create addition { 


} 


it Add a method to the addition class 

00::define addition method add {a b} { 
return [expr {$a + $b}] 

} 


addition create addObj 


puts "No Filter" 
puts "[LaddObj add 1 2]\n" 


i# Define a new method to show information about a method call 
o0o::define addition method show {args} { 

puts "——— [info level 0]" 

next {x}$args 


} 


# Show method information before all method calls 
# to addition objects 
00::define addition filter show 
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puts "With Filter" 
puts "[LaddObj add 1 2]\n" 


i## Create a global scope procedure for doubling a pair of numbers 
proc double {a b} { 

return [expr {$at+$a+$b+$b}] 
} 


it Add a forward to a global scope procedure 
o0o0::define addition forward sum2 double 


puts "double: [LaddObj sum2 1 2]\n" 


if Add a ‘sum’ method by re—using the ‘add’ method. 
o00::define addition forward sum my add 


puts "Using sum: [addObj sum 1 2]\n" 


i## Rename the sum2 method to twice 
00::define addition renamemethod sum2 twice 


puts "Renamed to twice: [addObj twice 1 2]\n" 


i Done with debugging now, delete filter method 
00::define addition deletemethod show 


puts "No More Filter" 
puts "[LaddObj add 1 2]\n" 


Script Output 


No Filter 
3 


With Filter 
— — addObj add 1 2 
3 


—-— addObj sum2 1 2 
double: 6 


—— addObj sum 1 2 
— my add 1 2 
Using sum: 3 


— -— addObj twice 1 2 
Renamed to twice: 6 
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No More Filter 


Modifying Inheritance 


Superclasses and mixins can be defined at runtime as well as inside the 00::class create command 
script. The superclass and mixin subcommands create (or recreate) the list of classes associated 
with this class, thus they will replace any previously defined superclasses or mixins. If you need to 
add a superclass or mixin without removing the current classes you can use the info class command 
(discussed later in this chapter) to find out what classes are currently defined. 


Adding a Superclass 

When a superclass is added to a class, the original class methods will be called first. These methods 
must use the next command to transfer control to a method with the same name in the super class. 
If there are multiple superclasses, the next command will transfer control to the next class in the order 
that they are defined. 


Syntax: 00::define className superclass className ?className? 
Assign one or more classes to the list of superclasses. 


className The name of the class (or classes) to assign 
as the list of superclasses. 


Mixing in a New Class 
When mixins are added to a class the mixin methods are called first and these methods must include a 
next command to transfer control to the base method with the same name. 


Syntax: 00::define className mixin className ?className? 
Assign one or more classes to the list of mixin classes. 


className The name of the class (or classes) to assign 
as the list of mixin classes. 


The next example shows using both superclasses and mixin classes. When both mixins and super- 
classes exist, the control goes first to the mixin, then to the base class, then to superclasses. If your 
code uses a next command when there is no method in the chain, Tcl will throw an error. You can use 
the catch command to invoke next when you don’t know whether or not a method will be the last 
method in a chain. 


22-]$AAAR99@a_o $$ 
Example 4 
Script Example 
00::class create base { 
method show {args} { 
puts "base show args: $args" 
catch {next "base::show args: $args"} 
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} 


0o0::class create addSuper { 
method show {args} { 
puts “addSuper show — $args" 
catch {next "addSuper::show args: $args"} 


} 


00::class create addMixin { 
method show {args} { 
puts “addMixin show — $args" 
catch {next "addMixin::show args: $args"} 


} 


base create basel 
puts "\nbase class" 
basel show "no super" 


puts "\nbase class with addSuper" 
oo::define base superclass addSuper 
basel show "with addSuper " 


puts "\nbase class with addSuper and addMixin" 
oo::define base mixin addMixin 
basel show “with super and mixin" 


Script Output 


base class 
base show args: {no super} 


base class with addSuper 
base show args: {with addSuper } 
addSuper show — {base::show args: {with addSuper }} 


base class with addSuper and addMixin 
addMixin show — {with super and mixin} 
base show args: {addMixin::show args: {with super and mixin}} 
addSuper show — {base::show args: \ 
{addMixin::show args: {with super and mixin}}} 
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10.1.3 Modifying Class, Constructor, Variables and Destructor 
A class can be fully defined with the 00::class create command, or you can use the 00::class 
create command to create an empty class and add the parameters using the oo: : define command. 
Defining a class dynamically can be useful when there are several similar classes to be created, or 
when your code creates on-demand classes to react to the external environment. 
If a constructor is added with the oo: : def ine command, it behaves exactly like a constructor that 
is created within an oo::class create script. 
The constructor subcommand requires a set of arguments and a constructor body script. 


Syntax: 00::define className constructor args script 
Define a constructor for a class. 
args The argument list for the constructor. 


script The script to evaluate when an object of this 
class is created. 


A destructor can be added much like the constructor, except that the destructor does not require any 
arguments. Note that the destructor will not return a value. 


Syntax: 00::define className destructor script 
Define a destructor for a class. 


script The script to evaluate when an object is 
destroyed. 


Like the mixin and superclass subcommands, the variable command will replace the variable 
list with a new list. You can add a new variable to a class using the info command discussed later in 
this chapter. 


Syntax: 00::define className variable variableNamel variableName2 
Set the variables for a class. 
variableNamex A list of variables for this class. 


The next example shows three classes being defined dynamically with the oo::class and 
o0o::define commands. This script defines three character basic classes for a fantasy game: the war- 
rior, mage and cleric. The initial hitpoints for a character of each class is hardcoded into the constructor, 
while the name of the character is passed when a character is created. 


_—————————— 
Example 5 
Script Example 
foreach type {warrior mage cleric} \ 
hits {8 4 6} { 

oo::class create $type 

oo::define $type variable hitpoints myName 

oo::define $type constructor {name} \ 

"set hitpoints $hits; set myName \$name" 
oo::define $type method display {} {return "$myName has $hitpoints"} 
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oo::define $type destructor {puts "$SmyName go bye—bye"} 
} 


set wl [warrior new Sigfried] 
set ml [mage new Brunhilda] 
puts "[L$wl display] hitpoints" 
puts "[$ml display] hitpoints" 
$ml destroy 


Script Output 
Sigfried has 8 hitpoints 
Brunhilda has 4 hitpoints 
Brunhilda go bye—bye 


10.1.4 Static Methods and Variables | 


The common use of object-oriented programming is to assign parameters and methods to objects 
and work with the objects. In some circumstances, however, it’s appropriate to assign a parameter 
or method to the class itself, not the objects instantiated from that class. 

The self subcommand performs an action on the class, rather than modifying the class definition 
and objects created from the class. Other techniques for creating static variables and methods are 
discussed later in this chapter. 


Syntax: 00::define className self action argl 
Perform an action upon a class. 
action A command to evaluate upon the class. 
args The arguments associated with the action. 


The next example shows a class that can have a limited number of objects created from it. The count 
of how many objects have been created is maintained in the class. A new method to create objects on 
this class is also attached to the class, not to the objects created from the class. 


=3$ $$ AAR9hal_ 
Example 6 
Script Example 
i## Define a class named limited. 
o0o::class create limited { 
constructor {} { 
puts "Creating new limited class" 
} 
method show {} { 
puts "This is an object of the limited class" 


} 
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if Define a variable count associated with the class, 
if not objects of this class 
00::define limited self variable count 


if Define a method to modify the count variable. 
00::define limited self method setCount {{val {}}} { 
if {$val ne ""} { 
set count $val 


return $count 


} 


if Define a method to create objects of this class. 
if This invokes the usual ‘new’ command to create objects. 


00::define limited self method make {} { 
puts "Count starts at: $count" 
if {$count > 0} { 

incr count —1 
puts "New count: $count" 
return [limited new] 

} else { 
error 


Exceeded available object count" 


} 


dt Only allow one limited object to be created. 
limited setCount 1 


if Confirm that an object can be created. 
set 11 [limited make] 


$11 show 


## Confirm that the second attempt fails 


set fail [catch {set 12 [limited make]} rtn] 
if {$fail} { 
puts "Create failed: $rtn" 
} 
Script Output 


Count starts at: 1 

New count: 0 

Creating new limited class 

This is an object of the limited class 

Count starts at: 0 

Create failed: Exceeded available object count 
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10.2 MODIFYING OBJECTS 


The 00: :objdefine command can be used to modify individual objects as well as all the objects in a 
class. The syntax is the same as the 00: : define command except that the name of a class is replaced 
with the name of an object. 


Syntax: 00::objdefine objectName script 


00::objdefine objectName ?subcommand ?argl arg2 ...? 

Define a feature of an individual object. 

className The name of the object to be modified. 

script A script with commands to modify the 
object. This may modify several features. 

subcommand A subcommand that defines a single feature 
to be modified. 

?argl arg2 ...? The arguments that a subcommand requires. 


Most of the subcommands supported by the 00::define command are also supported by the 
00::0bjdefine command. 
These subcommands are supported by both 00: : define and 00: :objdefine: 


method method methodName args script 
filter filter methodName ?methodName? 
forward forward newName actualCmd ?args? 


renamemethod renamemethod oldName newName 


deletemethod deletemethod methodName ?methodName? 


export export methodName ?methodName? 

unexport unexport methodName ?methodName? 

mixin mixinclassName ?className? 

variable variable variableNamel variableName2 ... 


The constructor, destructor, self, and superclass commands are only supported with 
00::define, not oo: :objdefine. 


10.2.1 Changing an Object’s Class 
In most object-oriented programming systems, once an object of a given class is created, it is a member 
of that class until it is destroyed. 

If the capabilities of the object change, it can be better to change the class, rather than encode all of 
the possible behaviors in a single class’s methods. 

The class subcommand of the 00: :o0bjdefine command changes an object from one class to 
another. The constructor is not called when an object changes class, but all of the old methods and 
variables are replaced by the methods and variables of the new class. 
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In some fantasy games (for example, the classic hack), when a character dies, a corpse is left 
behind. The corpse still has a name and possessions, but can no longer attack or defend itself. 

The next example shows a Fantasy hero in which we have a character base class, and two derived 
classes: |}iveCharacter and deadCharacter. The character’s name and possessions are stored in 
variables in the base class. The character’s attack strength is determined by the attackStrength 
method in the derived classes. The deadCharacter class adds a new method takePossession to 
allow a player to remove items from a dead character, but not from a live character. 


_———_aA—_A 
Example 7 
Script Example 

i## Create a base class with variables for name and 

i## a list of possessions, and a general method for accessing 

## the contents of class variables. 


00::class create character { 
variable possessions name 


constructor {nm args} { 
set name $nm 
set possessions $args 


} 


# Return the value of an object’s variable 
## NOTE: No error checking. Variable must be valid. 
method get {id} { 

return [set $id] 


} 


i## Create a class for live characters. 

## Derives from character. 

if Includes a method for attacking 

00::class create liveCharacter { 
superclass character 


## Pass control to superclass constructor 
constructor {args} { 
next {x*x}$args 


} 


## Return attack strength 
method attackStrength {} { 
return 8 
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} 


dt Create a class for dead characters. 
if There is no constructor 
if The attackStrength method returns a 0 for attack. 


00::class create deadCharacter { 
superclass character 
variable possessions 


method attackStrength {} { 
return 0 


method takePossession {} { 
set taken [lindex $possessions 0] 
set possessions [lrange $possessions 1 end] 
return $taken 


set charl LliveCharacter new Sigfried Spear Tarnhelm] 


puts "[$charl get name] possesses [$charl get possessions ]" 
puts "[$charl get name] attacks with strength of \ 

[$charl attackStrength]" 

puts "After dieing,” 
00::objdefine $charl class deadCharacter 

puts "[$charl get name] possesses [$charl get possessions]" 
puts "[$charl get name] attacks with strength of \ 

[$charl attackStrength]" 

puts "Took [$charl takePossession] from [$charl get name]" 
puts "Took [$charl takePossession] from [$charl get name]" 


Script Output 
Sigfried possesses Spear Tarnhelm 
Sigfried attacks with strength of 8 
After dieing, 
Sigfried possesses Spear Tarnhelm 
Sigfried attacks with strength of 0 
Took Spear from Sigfried 
Took Tarnhelm from Sigfried 
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10.2.2 Defining Per-object Mixins 

Adding a mixin to the class definition is useful for features that will be permanent and are shared by all 
members of a class. Some features may be object specific (for example, an employee’s skills) or may 
not be permanent (for example, an employee’s security status). 

You can add a mixin to an individual object with the mixin subcommand. The object specific 
mixin subcommand has the same behavior as the class version of the command, except that a mixin 
is added to a single object. 

An object has a two lists of mixin classes. One list is the mixins assigned to the class and the other 
is the mixins assigned to an individual object. 

This example shows a fantasy character obtaining a spear and magic helmet as mixins. The magic 
helmet is mixed into the warrior class in the class definition. The spear is mixed into the object. The 
object mixin methods are invoked before the class mixin methods. 


——_—>NADA a A A 
Example 8 
Script Example 
00::class create magicHelmet { 
method defense {attackStrength} { 
puts "Magic Helmet Reduces attack by 2" 
return [next [expr {$attackStrength — 2}]] 


00::class create spear { 
method defense f{attackStrength} { 
puts "Spear reduces attack by 2" 
return [next [expr {$attackStrength — 2}]] 


} 


00::class create warrior { 
mixin magicHelmet 


constructor {} { 

variable State 

array set State {defense 4 attack 4 hitpoints 5} 
} 


method defense {attackStrength} { 
variable State 
puts "Final Attack is: $attackStrength" 
if {$attackStrength > $State(defense)} { 
return "Hit" 
} else { 
return "Missed" 
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warrior create elmer 


puts "With only a magic helmet" 
puts "With a magic helmet elmer is [elmer defense 8]" 


puts "\n Add a spear to the elmer object" 
o00::objdefine elmer mixin spear 
puts "With spear and magic helmet elmer is [elmer defense 8]" 


Script Output 
With only a magic helmet 
Magic Helmet Reduces attack by 2 
Final Attack is: 6 
With a magic helmet elmer is Hit 


Add a spear to the elmer object 

Spear reduces attack by 2 

Magic Helmet Reduces attack by 2 

Final Attack is: 4 

With spear and magic helmet elmer is Missed 


10.2.3 Adding a Method to an Object 
Most methods are defined within the 00::class create script or with the 00: : define command. 
These methods are common to all members of a class. 

We can create an object-specific method with the method subcommand. This method may have a 
unique name, or may override the name of an existing method defined for all objects in the class. If 
the name is overriding an existing class-defined method, the object method will be called first and may 
pass control to the class method with the next command. 

In the case of overriding the class-defined method with an object-specific method, both methods 
exist in the method chain. The object-specific method will be invoked first and may either return 
(breaking the chain), or can pass control to the rest of the method chain with the next command. 

In the next example a new defense method is added to the el mer object. 


10.3 EXAMINING CLASSES AND OBJECTS 


One difference between Tcl and most other languages is the amount of introspection available to the 
script writer. Information that needs to be hard-coded in other languages can be determined at run-time 
in Tcl. This makes it possible to write generic routines that adapt to new conditions, rather than coding 
information about the application into the application. 
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The info command is the tool that provides information into the configuration of the Tcl 
interpreter. 
The basic form of the info command for classes and objects is: 


Syntax: info class subcommand className args 
info object subcommand objectName args 


Return information about a class or object. 


subcommand A subcommand describing what info should 
be returned. 


className The name of aclass to examine. 
objectName The name of an object to examine. 


args Other arguments that may be required (name 
of a method, etc.). 


The return value from info class and info object may not be the same. The class com- 
mands return information that is common to all members of a class. The object commands return 
information for only a single object. When separate lists are maintained for object and class (as is done 
for mixins), the commands return the value specific to a given list, not common to both lists. 

The previous example has a : :magicHelmet mixin attached to the warrior class anda :: spear 
mixin attached to the elmer object. 

The info class mixin warrior command returns ::magicHelmet while info object 
mixin elmer returns ::spear. 


10.3.1 Evaluation of Chains 


When one class acquires properties from another class, either by inheritance or with a mixin, control 
is passed from one class to another. In order to pass control from one class to another, TclOO creates 
a chain of elements to evaluate when a user requests an action. There is a chain of constructors when 
an object is created, a chain of methods when a method is invoked, and a chain of destructors when an 
object is destroyed. 

The method chain is constructed in the same order for constructors, destructors and methods. The 
following list shows the order in which items will be evaluated. Note that the second step only applies 
to methods and destructors since a constructor is evaluated before an object exists. 

If a method can appear in the chain more than once (perhaps a class has been included both as a 
super and a mixin), it will be added at the latest valid position. 


Filter Methods If multiple filters are associated with a class, they appear in the order of the class 
hierarchy. 


Object Methods A method defined for this object (with 00: :objdefine method) is evaluated 
next. 


Object Mixin Methods Method defined in the mixin list associated with the object, from first to 
last in the order of the list of mixins. Per-object mixins are defined with the 00::objdefine 
command, as described above. 
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Class Mixin Methods Methods defined in the mixin list associated with the class, from first to last 
in the order of the list of mixins. These mixins are defined with the 00::class create command 
or an 00: :define command. 


Class Method The method in the current class. This might be defined in the 00::class create 
script or with the oo: :define command. 


Superclass Methods The method defined in superclass list for the class, from first to last in the list 
of superclasses. If a superclass has one or more mixins defined, those mixins will appear before the 
superclass. 


The next command evaluates the next method in the chain and returns to the method that invoked 
next. The next command can come early in a procedure or late. Your procedure can modify the 
parameters that will be passed to the next method in the chain, or modify the values after the next 
method has returned. 

If there is no next command in a method, the evaluation will stop with the current method and not 
proceed to other elements of the chain. 

Including a catch next command in constructors, methods and destructors is one way to allow a 
class to be reused for other applications. This is particularly true of classes that are expected to be used 
as mixins to massage values before other processing. 

The example below shows a set of classes that use superclass and mixin inherit functionality. 
The constructors and methods are dummies that display when they are invoked in order to show the 
chain. 

The class hierarchy is shown in the following illustration. The bottom, middle and top classes 
inherit from each other using the superclass command, while mixerl and mixer2 are inherited 
using the mixin command. Each class has a show method which displays the class that contains it. 


Constructor Method and Destructor Chaining 


a mixer2 
mixin 


show - Mixer2 Show 


middle 


constructor 
show - Middle Show 


mixerl 


show - Mixer! Show 


bject-specifi 00::objdefine 
show - Bottom Show athe ic ——eoaerrX— 
show - Defined Show 
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The following example uses this class hierarchy to create an object, showing order in which the 
constructors are chained together. It then invokes the show method, again showing how the chain is 
constructed. Finally, a new show method is added to the test object to show that the object’s method 
is placed first in the chain. 


2. AHAA$pvANRAa9@9o9a2O3]_4}4iI 
Example 9 
Script Example 
00::class create mixerl { 
constructor {} { 
puts "Mixerl Constructor" 
catch {next} 
} 
method show {} { 
puts "Mixerl Show" 
catch {next} 


} 


00::class create mixer2 { 
constructor {} { 
puts "Mixer2 Constructor" 
catch {next} 
} 
method show {} { 
puts "Mixer2 Show" 
catch {next} 


} 


00::class create top { 

mixin mixer2 

constructor {} { 
puts "Top Constructor" 
catch {next} 

} 

method show {} { 
puts "Top Show" 
catch {next} 


} 


00::class create middle { 
superclass top; 
constructor {} { 
puts "Middle Constructor 
catch {next} 
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} 

method show {} { 
puts "Middle Show" 
catch {next} 


} 


00::class create bottom { 
superclass middle; 
mixin mixerl; 
constructor {} { 
puts "Bottom Constructor" 
catch {next} 
} 
method show {} { 
puts "Bottom Show" 
catch {next} 


puts "Order of constructors" 
bottom create test 


puts "\nOrder of methods being invoked" 
test show 


puts "\nOrder of methods after oo::objdefine method" 
00::objdefine test method show {} { 

puts "Defined Show"; 

catch {next} 


} 


test show 


Script Output 


Order of constructors 
Mixerl Constructor 
Bottom Constructor 
Middle Constructor 
Mixer2 Constructor 
Top Constructor 


Order of methods being invoked 
Mixer1 Show 

Bottom Show 

Middle Show 

Mixer2 Show 

Top Show 
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Order of methods after oo::objdefine method 

Defined Show 

Mixerl Show 

Bottom Show 

Middle Show 

Mixer2 Show 

Top Show 

= 

Including the next command in all constructors, methods and destructors ensures that control will 
propagate through the chain in the order that TclOO defines. 

This is not always what you want to occur. 

The nextto command will send control to a specific element of the chain. The next to command 
can be used to invoke functions in any desired order. 

Instead of using next to step through the functions, your code can use the nextto command to 
invoke functions in a the order you want them invoked. The downside to this technique is that it requires 
that the first method invoked knows the rest of the call hierarchy. If an object acquires a mixin, that 
mixin’s method will be the first method on the list and will either need to know the rest of the hierarchy 
or use the next command to pass control into the class-specific methods. 


Syntax: nextto className args 
Invoke the method in the defined class. 


className The name of a class with a method of the 
same name as the method calling nextto. 


args Any arguments required by the method in the 
defined class. 


You can mix next and nextto commands within a class structure and even within a single method. 
Note that invoking next or nextto more than once can cause the underlying functions to be evaluated 
multiple times. 

In the previous example the mi xer1 constructor is the first to be invoked. If that constructor is mod- 
ified to use nextto instead of next some constructors can be skipped. In this example, the constructor 
for bottom (the class of the object being created) is skipped. 


eee eee 
Example 10 


Script Example 


00::class create mixerl { 
constructor {} { 
puts "Mixerl Constructor" 
catch {nextto middle} 


} 
Script Output 


Order of constructors 
Mixerl1 Constructor 


SSS 5] 
290 CHAPTER 10 Advanced Object-Oriented Programming in Tcl 


Middle Constructor 
Mixer2 Constructor 
Top Constructor 


Unless you have a tightly defined class hierarchy, you will want to examine the call chain before 


doing very much with next and nextto. You can determine the chain for a constructor, method or 
destructor with the info class call orinfo object call commands. 


Syntax: info class call className methodName 
info object call objectName methodName 
Return a list describing the call chain for the given method. 
className The name of the class associated with this 
method. 
objectName ‘The name of the object associated with this 
method. 


methodName The name of the method to be queried. 


The cal 1 subcommand returns a list of lists. Each list element consists of four fields: 


1. 


General type of element. This will be one of 


e method: This is a normal method. 

e fi1ter This is a method attached as a filter. 

e unknown If the method is attached by some other technique. 
The name of the method. 


. The class this method is associated with. If the method is attached directly to an object, this will be 


the word object. 
Specific type of method—this is the value that is returned by the methodtype subcommand, which 
will be discussed later in this chapter. 


Adding these commands to the end of the previous example produces the following output. Notice that 
the object call output is almost identical to the class cal] output, except that it shows the show 
method that was attached to the object as well as the normal class-defined methods. 


——o— OO —-n—e—eeeee—m 
Example 11 


Script Example 


puts "CLASS CALL" 

foreach link Linfo class call bottom show] { 
puts $link 

} 
puts "\nOBJECT CALL" 

foreach link [info object call test show] { 
puts $link 


} 
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Script Output 
CLASS CALL 
method show ::mixer1l method 
method show ::bottom method 
method show ::middle method 
method show ::mixer2 method 
method show ::top method 


OBJECT CALL 

method show object method 
method show ::mixer1l method 
method show ::bottom method 
method show ::middle method 
method show ::mixer2 method 
method show ::top method 


If a filter is added to a class, it will be called first, regardless of where it appears. If there are multiple 
filters, they are called in the order of the class hierarchy. 
The next example adds a couple of filters to the code above and shows the new cal] output: 


$$ A 
Example 12 
Script Example 
i## Define a new method in class ‘top’ 
oo::define top method testfilter {args} { 
puts "top filter"; 
next 


} 


if Define a new method in class ‘middle’ 
00::define middle method testfilter {args} { 
puts "middle filter"; 
next 


} 


if Add the new methods as filters 
o0o::define top filter testfilter 
00::define middle filter testfilter 


Script Output 
OBJECT CALL after adding filter 
filter testfilter ::middle method 
filter testfilter ::top method 
method show object method 
method show ::mixerl method 
method show ::bottom method 
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method show ::middle method 
method show ::mixer2 method 
method show ::top method 


If a class has forwarded methods, the class command only shows the chain up to the forwarded 
method. 


Adding these lines to the previous example demonstrates how the filters are seen immediately, but 
the last element to be shown in the chain is the forwarded method. 


——— een 
Example 13 


Script Example 


o0o0::define bottom forward testforward my show 


puts "\nCLASS CALL for testforward" 

foreach link [info class call bottom testforward] { 
puts $link 

} 


Script Output 
CLASS CALL for testforward 
filter testfilter ::middle method 
filter testfilter ::top method 
method testforward ::bottom forward 


The rest of the information about a forwarded method (like, what it’s been forwarded to) can be 
obtained. This will be discussed in the next section. 


10 Examining Methods 


If you are examining a class or object, you may need to examine the methods, method arguments 
and method bodies as well as the execution chain. This facility is useful for writing general-purpose, 
class-driven serialization functionality, or for constructing classes on the fly with a clone-and-modify 
function. 

The info commands that give you information about methods are implemented for both classes 


and objects. The subcommands are listed below. 
info class methods Returns a list of methods. 
info class methodtype — Returns the type of method. 
info class definition — Returns full information about a method. 


info class constructor Returns the arguments and body of a 
constructor. 


info class destructor — Returns the body of a destructor. 
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info class forward Returns the script that this command is 
forwarded to. 


info class filterss Returns a list of filters. 


One place to start examining a class’s or object’s methods is just to get a list of the methods. The 
info class methods and info object methods commands behave slightly differently. 


Syntax: info class methods className 
Return a list of methods associated with a class. 
className The class with methods to be returned. 


?-all? By default, info class methods returns only the methods 
defined in this class. When the -al1 flag is added methods 
associated with the superclasses and mixins are also returned. 


Syntax: info object methods objectName ?-all? 
Return a list of methods associated with a object. 
objectName The object with methods to be returned. 


?-all? By default, info object methods returns only the 
methods defined for the object using the 00: : objdefine 
method command. When the -a11 flag is added methods 
associated with the class and mixins are also returned. 


The next examples revisit the class for a fantasy role-playing character. The class has methods for 
show and defense. After a character is created, we add an object-specific method to cast lightning 
(cast). 

The info class methods call displays the methods defined for the class show and defense. 
The first info object methods call only shows the cast method. When the -al1 flag is added, it 
displays the class methods and also the destroy method for deleting the object. 
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Example 14 


Script Example 


if Define a character class with minimal methods. 


00::class create character { 
variable State 
constructor {nm} { 
array set State {defense 2 attack 2 hitpoints 5} 
set State(name) $nm 
} 
destructor { 
puts "$State(name) is gone" 
} 
method show {args} { 
parray State 
} 
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method defense {attackStrength} { 
if {$attackStrength > $State(defense)} { 
return "Hit" 
} else { 
return "Miss" 


} 


if Create a character named Sigfried and 
i## give him a sing method 


character create elmer Sigfried 
00::objdefine elmer method cast {} { 


puts "Lightning Flash. Thunder Roar." 


puts "The methods for the character class are:" 
puts [info class methods character]" 


puts "The methods for the object elmer are:" 
puts Linfo object methods elmer]" 


puts "All the methods for the object elmer are:" 
puts Linfo object methods elmer —all1]" 


Script Output 
The methods for the character class are: 
show defense 
The methods for the object elmer are: 
cast 
All the methods for the object elmer are: 
cast defense destroy show 


We can quickly add an attack method to the class by creating a simple procedure and adding it to 
the class with the 00::define character forward command. 

The new code and a command to view the methods are shown in the next example. The new method 
attack is shown in the list of class methods. 
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Example 15 


Script Example 


00::define character forward attack attackStrength 


proc attackStrength {} { 
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return 8 


} 


puts "After adding forward, the methods for the character class are:" 
puts " [info class methods character ]" 


Script Output 


After adding forward, the methods for the character class are: 
attack show defense 


We can add a filter method to test that input is a valid integer. This filter replaces invalid input 
with a 0. 
The new code to define a method and then add it as a filter looks like this: 
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Example 16 
Script Example 
oo::define character method inputTest {val} { 
if {!Lstring is integer] $val} { 
set val 0 


} 


next $val 


} 


00::define character filter inputTest 


puts "After adding filter, the methods for the class are:" 
puts " [info class methods character ]" 


Script Output 


After adding filter, the methods for the class are: 
inputTest attack show defense 


The output from this example shows that inputTest is added to the list of methods associated 
with the class, but doesn’t tell us whether this is a filter, a forward or a normal method. 

The info class methodtype command reports whether a method is a regular method or a for- 
ward. A filter is a normal method and isn’t distinguished. We can get a list of a class’s filters with the 
filters subcommand 

Using the filters command to get a list of the filters is shown below. 
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Example 17 


Script Example 


puts "The filters defined for the character class are:" 
puts " [info class filters character ]" 
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Script Output 


The filters defined for the character class are: 
inputTest 


We can get information about the arguments and body of a method with the definition and 
forward subcommands. These subcommands each return a two-element list. The first element will be 
a list of the method’s arguments and the second element is the body of the method. 

These commands are sufficient to construct a procedure which will serialize a class and generate 
output suitable for rebuilding the class. 

The example below is a procedure that will accept the name of a class and will generate the code 
to reconstruct the class. This can be used to save or view a simple class definition. The next section 
discusses how to handle classes with superclasses and mixins. 

Note that the info commands do not distinguish between methods added in the 00::class cre- 
ate script and methods added with an 00: : define command. The 00::class create command 
invokes the 00::define command to add methods, thus there is no distinction between methods 
added with either command. 
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Example 18 


Script Example 


proc defineClass {className} { 

puts “oo::class create class $className {" 
foreach m [info class methods character] { 

switch Linfo class methodtype character $m] { 

forward { 
set forwardTo Linfo class forward character $m] 

append cmds "\nfF Method $m is forwarded to $forwardTo\n" 
pend cmds "oo::define $className forward $m $forwardTo\n" 
t procArgs Linfo args $forwardTo] 
t procBody Linfo body $forwardTo]] 
pend cmds [list proc $ procArgs $procBody ] 


method { 
puts "\n# Definition of method $m" 
puts "method $m [info class definition character $m]" 


puts "}" 


puts "\nf# These filters are defined for $className" 
foreach f Linfo class filters $className] { 
puts “oo::define character filter $f" 
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puts "\n # These forwards are defined for $className" 
puts $cmds 


puts "Full definition" defineClass character 


Script Output 


00::class create class character { 


# Definition of method inputTest 
method inputTest val { 
if {! [string is integer] $val} { 
set val 0 


} 


next $val 


# Definition of method show 
method show args { 
parray State 


# Definition of method defense 
method defense attackStrength { 
if {¢attackStrength > $State(defense)} { 
return "Hit" 
} else { 
return "Miss" 


# These filters are defined for character 
oo::define character filter inputTest 


# These forwards are defined for character 


# Method attack is forwarded to attackStrength 
oo::define character forward attack attackStrength 
proc attack {} { 

return 8 
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10 Examining Inheritance 
The dynamic nature of TclOO’s way of handling superclasses and mixins can lead to unexpected 


combinations of classes. Fortunately, the info command has tools to untangle a web of classes and 
make sense of them. 


The subcommands that provide information about the class hierarchy are: 
info class superclasses Returns a list of superclasses. 


info class subclasses Returns a list of subclasses. 

info class mixins Returns a list of mixins attached to a class. 

info object mixins Returns a list of mixins attached to an object. 

The superclasses and subclasses subcommands let you trace what classes are derived from 
each other. 


Syntax: info class superclasses className 
Returns a list of superclasses. 


className The name of the class to return superclasses 
for. 


If you need to know what classes are derived from a given class, you can use the subclasses 
subcommand. 


Syntax: info class subclasses className ?pattern? 
Returns a list of classes derived from this class that match an optional pattern. 


className The name of the class to return superclasses 
for. 


pattern An optional glob-pattern to limit the number 
of derived classes to return. 


The next example shows the character class and a warrior class that’s derived from it. The info 
class commands show the superclass and subclass relationships. 
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Example 19 
Script Example 


i## The base character class 
oo::class create character { 
variable State 
constructor {nm} { 
array set State {defense 2 attack 2 hitpoints 5} 
set State(name) $nm 


} 


method defense {attackStrength} { 
if {$attackStrength > $State(defense)} { 
return "Hit" 
} else { 
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return "Miss" 


if A warrior gets better attack and defense skills 
00::class create warrior { 
superclass character 


variable State 
constructor {name} { 
puts "Warrior constructor" 
next $name 
incr State(defense) 2 
incr State(attack) 2 


puts "These classes superclass from character" 
puts " [info class subclass character ]" 


puts "The superclass for warrior is" 
puts " [info class superclass warrior ]" 


Script Output 
These classes superclass from character 
::warrior 
The superclass for warrior is 
::character 


10.3.4 Getting a List of Base Classes 

The TclOO class hierarchy is a singly-rooted hierarchy. At the base is the 00: :object class. All 

classes are subclasses of the 00: : object class from which they inherit the default destroy method. 
A dynamic TclOO application might define new classes while it’s running. We can use the info 

class subclasses command with the 00::object class to get a list of all the defined classes as 

shown in the next example. Only the top level classes that have been defined show up as subclasses of 

o0o0::object. The subclasses subcommand does not recurse into the class hierarchy. 
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Example 20 


Script Example 


info class subclasses oo::object 
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Script Output 
::character 


If our hero should find a magic helmet to wear it should be added as a mixin to the object for our 
hero, not to the warrior class. The info class mixinand info object mixin commands return 
different values in the next example. 


Syntax: info class mixins className 
info object mixins className 
Returns a list of classes mixed into the named class or object. 


className The name of the class to return superclasses 
for. 


The next example adds a magicHelmet class, creates a hero, and uses the mi xin command to give 
him the helmet. The info class mixin command returns an empty list, while the info object 
mixin command shows that elmer has a magic helmet. 
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Example 21 
Script Example 
if The base character class 
00::class create character { 
variable State 
constructor {nm} { 
array set State {defense 2 attack 2 hitpoints 5} 
set State(name) $nm 


} 


method defense {attackStrength} { 
if {$attackStrength > $State(defense)} { 
return "Hit" 
} else { 
return "Miss" 


if A warrior gets better attack and defense skills 
00::class create warrior { 
superclass character 


variable State 

constructor {name} { 
puts "Warrior constructor" 
next $name 
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incr State(defense) 2 
incr State(attack) 2 


00::class create magicHelmet { 
method defense {attackStrength} { 
puts "Magic Helmet Reduces attack by 2" 
return [next [expr {$attackStrength — 2}]] 


warrior create elmer Sigfried 
00::objdefine elmer mixin magicHelmet 


puts "Class Mixins: [info class mixins warrior]" 
puts "Elmer’s Mixins: [info object mixins elmer ]" 


Script Output 
Warrior constructor 
Class Mixins: 
Elmer’s Mixins: ::magicHelmet 


EXAMINING OBJECTS 


In order to save an application’s state, we need to record that state of the objects, as well as the class 
hierarchy. There are more info commands that report information about the objects. 

The first step in getting information about an object is to find out what classes and objects exist. The 
info class subclasses command does not recurse into the class hierarchy, but this command can 
be wrapped with a recursive procedure to return the complete list of defined classes. The next example 
is a recursive procedure that returns a list of all the classes that are defined. 


A$$ 
Example 22 
Script Example 
proc findClasses {parent } { 
set childClasses Linfo class subclasses $parent] 
if {$childClasses eq ""} { 
return 
} else { 
set children $childClasses 
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foreach cl $childClasses { 
## To protect from looping, confirm that 
if each class is only included once. 
foreach gch [findClasses $cl] { 
if {Llsearch $children $gch] < O} { 
lappend children $gch 


} 
} 


return $children 


Given a list of classes, the next step is to learn what objects have been instantiated from each class. The 
info class instances command will return the names of objects instantiated from a class. On the 
flip side, the info object class command will return the class of an object. 

The previously discussed commands can be used to extract the method, superclass and mixin 
information for an object. Getting the contents of variables requires a bit more work. 

One technique is to create generic methods to assign and retrieve values from object variables. A 
new method to examine and modify variables associated with the warrior object elmer is shown in 
the next example. This type of a procedure can be useful in any class. The ability to access an object’s 
variables breaks the black-box concept of object-oriented programming, but it’s often preferable to 
having set/get routines for each variable that might need to be accessed outside a class. 

The variable command must be used in this method to map the object variables into the local 
scope because this method is designed as a mixin, not part of the class definition defined with the 
oo::class create command. 
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Example 23 


Script Example 


00::objdefine elmer method config {name args} { 
if {[set p [string first "(" $name]] > 0} { 


incr p -l 
set varName [string range $name 0 $p] 
} else { 


set varName $name 


} 


variable $varName 


if {$args ne ""} { 
set $name {x}$args 


} 


return [set $name] 
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puts [elmer config State(attack)] 
puts Lelmer config State(attack) 6] 


Script Output 


4 
6 


A routine like this can be used to examine an object’s variables and to create a serialized image of an 
object. The list of variables defined for an object is returned by the info object vars command. 


Syntax: info object vars ?pattern? 
Return an object’s variables as a list. 


pattern Return only the variables with names that 
match this pattern. 
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Example 24 


Script Example 


puts Linfo object vars elmer] 


Script Output 


State 
| 


Another technique for examining variables is to use the namespace commands. The basis of the 
TclOO package is the Tcl namespace. Each class definition and each object is contained in a separate 
namespace. When you create a new object with the new command (not the create command) the 
return value for that object is the namespace. If you know the object’s namespace, you can use the 
namespace commands to examine and recreate it. 

If an object was created with the create command, the return value is the name defined in your 
script, not a namespace path. The info object namespace command will return the namespace 
associated with an object whether the object was created with new or create. 


Syntax: info object namespace objectName 
Return the namespace for an object. 


objectName The name of the object. 


The next example shows an object serialization procedure that uses the previously discussed find - 
Classes procedure. This procedure will return a set of commands to rebuild all the objects in a system. 
Note that while this generic procedure will work for many class hierarchies, it’s not guaranteed to work 
for all class hierarchies. The Tcler’s wiki (http: //wiki.tcl.tk) has discussion of other techniques 
for serializing objects. 
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The info class instances command will return all objects that have instances of a class— 
this includes objects that use a class as a mixin. For instance, since our hero elmer has a mixin 
of magicHelmet, the command info instances magicHelmet will return elmer as an object 
instantiated from this class. 

The test to confirm that info object class $obj returns the same value as the class used in 
info class instances reduces the list of objects to only objects that are truly members of a class. 

Objects can be created with a new or create command. When the new command is used, the name 
of the object is the same as the name of the namespace that contains the object’s variables. The test to 
see if the object name is the same as the namespace name determines which command should be used 
to recreate an object. 
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Example 25 
Script Example 
proc findClasses {parent } { 
set childClasses Linfo class subclasses $parent] 
if {$childClasses eq ""} { 
return 
} else { 
set children $childClasses 
foreach cl $childClasses { 
## To protect from looping, confirm that 
i## each class is only included once. 
foreach gch [findClasses $cl] { 
if {Llsearch $children $gch] < O} { 
lappend children $gch 
} 


} 
} 


return $children 


proc serializeAl|lClasses {} { 
foreach cl [findClasses oo::object] { 
set comment "# Rebuilding members of class $cl1" 
foreach obj Linfo class instances $cl] { 


i## Check that an object is truly a member of this 
# class. 
# A mixin class will report objects that include 
# the mixin. 
if {Linfo object class $obj] eq $cl} { 


set ns Linfo object namespace $obj] 
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if Check to see if this object was created with 
if a ‘new’ or ‘create’ command, to rebuild correctly. 
if {$ns eq $obj} { 
set cmd "new " 
} else { 
set cmd "create [string trim $obj ::]" 
} 
append cmds "$comment\n" 
append cmds “set obj \[$cl $cmd {} \]\n" 
append cmds "set ns \Linfo object namespace \$obj]\n" 
foreach var Linfo object vars $obj] { 
if {[catch {array get ${ns}::$var} arrayDef]} { 
append cmds \ 
"set \${ns}::$var Llist [set ${ns}::$var]]\n" 
} else { 
append cmds \ 
"array set \${ns}::$var Llist $arrayDef]\n" 


} 
} 
set comment "" 
} 
} 


return $cmds 


} 
puts [serializeAl]Classes] 


Script Output 
set obj [::warrior create elmer {} ] 
set ns [info object namespace $obj] 
array set ${ns}::State {attack 4 name Sigfried \ 
hitpoints 5 defense 4} 


10.5 USING TCLOO WITH CALLBACKS 


Several Tcl commands including fileevent, after, and various Tk widgets perform callbacks when 
some event occurs. In order to register a callback within an object’s method and have the callback be 
directed to a method in the same object, the code within that method needs to be able to introspect the 
current object. 

The info commands provide information about classes and methods, but they aren’t always appro- 
priate for use within a method. The self command allows a method to introspect itself. The self 
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command has several subcommands. The man page for self describes all of the subcommands. To 
register an object and method for a callback, we need the self object command. 


Syntax: self object 
Return the name of the object in which code is being evaluated. 


If the se] f command is used with no subcommand, it defaults to the sel f object behavior. 

This example shows how the self command can be used with the after command to create a 
callback that will be invoked at least once. If the repeat variable is true it will nag the user every 
second. 
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Example 26 
Script Example 
00::class create timer { 
variable interval repeat 
constructor {int rpt} { 
set interval $int 
set repeat $rpt 
puts "Registering [self] for a $interval ms callback" 
after $interval \ 
[list [self] alert "$interval milliseconds have elapsed" ] 


} 


method alert {msg} { 
puts $msg 
if {$repeat} { 
after 1000 \ 
[list [self] alert "You’ve missed the alert!"] 


} 


timer create twoSeconds 2000 1 


vwait forever 


Script Output 


Registering ::twoSeconds for a 2000 ms callback 
2000 milliseconds have elapsed 

You’ve missed the alert! 

You’ve missed the alert! 


The trace command will evaluate a callback when a variable is modified. In order to trace an object’s 
variable with the trace command, the trace command needs the full namespace path to the variable. 
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The my varname command returns the rooted namespace path for an object variable. This value 
can be supplied to the trace command just as you would otherwise provide the name of a variable in 
the current scope. 


Syntax: my varname variableName 
Returns the full namespace path to a named variable. 
variableName The simple variable name. 


The callback for the trace command can be another class method or a global scope procedure. The 
trace callback is performed in a procedure scope below the level where the assignment occurs; thus the 
variable name can always be mapped into the callback’s scope with the upvar command. 

If the callback procedure is a method within the class, then the code that registers the callback must 
use the sel f command to provide the object context to invoke. 

The example below shows a class with two variables, var1 and var2. Each variable has a trace 
attached to it. The var1 callback is a global scope procedure, while the var2 callback is a method 
within the withTrace class. 
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Example 27 
Script Example 
00::class create withTrace { 
variable varl var2 
constructor {} { 
set varl 2 
set var2 2 
trace add variable [my varname varl] write \ 
showVar 
trace add variable [my varname var2] write \ 
[list [self] showVar] 
puts "Full path for varl is: [my varname varl]" 


method decrVarl {} { 
incr varl —-1l 


method decrVar2 {} { 
incr var2 —2 


method showVar {name index operation} { 
pvar $name vv 
puts "Method shows new value for $name is $vv" 


} 


proc showVar {name index operation} { 
upvar $name vv 
puts "Global proc shows new value for $name is $vv" 


} 
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withTrace create test 
test decrVarl 
test decrVar2 


Script Output 
Full path for varl is: ::00::0bj4::varl 
Global proc shows new value for vari is 1 
Method shows new value for var2 is 0 


The self and my varname commands are used to link objects with Tk widgets. These uses will 
be discussed in more detail in the next Tk chapters, but here’s a brief overview. 

The self command is used to link a callback to a Tk widget that needs context for the callback. 
Using an object method and the argument to the - command option of the button widget requires the 
self command to provide this context. 

The my varname command must be used to link a Tk widget with a variable using the widget’s 
-textvariable option. 


10.6 ADDING NEW FUNCTIONALITY TO TCLOO 


TclOO is a sufficiently complete object-oriented system to be useful, but the original intent was that 
TclOO would be the framework for building more complex and complete OO systems. 
This section will discuss some of the hooks for adding new commands and features to TclOO. 


Static Variables II 


A class or static variable is a variable that is attached to the class, rather than the objects. For example, 
if the objects of a class use a scarce resource and you need to control the number of instantiated objects 
you might use a class variable to keep track of the number of objects that have been created in that 
class. 

A class variable can be implemented as a link (using upvar from a variable in the object’s names- 
pace to a variable in the class definition namespace). To do this we need to determine the namespace 
where the class is defined and the namespace of the object being created. 

The code in the next example creates anew classvar definition that can be added to a constructor 
(as shown in the 1 imitedI tem example). Since the cl assvar command is creating upvar links in an 
object’s namespace, the command needs to be evaluated inside the constructor, after a new namespace 
has been created, rather than as a standalone command in the class definition script. 

The classvar procedure could be placed in any namespace (even the global scope). The 
::00::Helpers namespace is one which TclOO maintains. A procedure placed in this namespace 
is available to all methods and definition scripts. 

The first few lines of the classvar procedure introduce some new commands and concepts. 

The self command provides information about the object that contains the code being evaluated. 
The self class command returns the name of the class being created. 


10.6 Adding New Functionality to TclOO 309 


Syntax: self class 
Return the name of the class. 


When the Tcl interpreter evaluates a set of code, it evaluates that code in the namespace in which 
the code was originally defined. The classvar procedure is evaluated in the ::00::Helpers 
namespace. 

The up! evel command allows commands to be evaluated in the scope of the calling procedure. 

If the classvar procedure tried to determine its class using self class without the upvar, 
the self command would be evaluated in the ::00::Helpers namespace, not in the new object’s 
method namespace. The sel f command is only valid when evaluated within a method. 

Once the name of the class is determined, the info object namespace command can be used 
to determine the class definition namespace. 

Similarly, the namespace current command needs to be evaluated in the calling scope, not the 
classvar procedure’s scope. 

A fantasy game needs some magical items, but not too many. The next example shows the class - 
var procedure and a class that uses a class variable to keep track of how many items of this class have 
been created and will only allow two items to be made. 
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Script Example 
proc ::00::Helpers::classvar {args} { 
## Get reference to class’s namespace 
set nsCl Linfo object namespace [uplevel 1 {self class}]] 
set nsObj Luplevel 1 {namespace current} ] 
# Link variables into local (caller’s) scope 
foreach v $args { 
uplevel "my variable $v" 
upvar #0 ${nsCl}::$v ${nsObj}::$v 


} 


00::class create limitedItem { 

constructor {} { 
classvar quantity 
# Initialize quantity the first time a limitedItem is created 
if {!Linfo exists quantity]} { 
set quantity 1 
} 
if {$quantity > 2} { 
error "Too many magical items" 
} 


incr quantity 


} 


wu 


set magicRings 
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foreach ring {diamond ruby amethyst emerald garnet gold silver} { 
if {Lexpr {rand()}] > .5} { 
set fail [catch {limitedItem create $ring} rtn] 
if {!$fail} { 
lappend magicRings $rtn 
} else { 
puts "FAILED: $rtn" 
} 
} 
} 


puts "Defined $magicRings rings" 


Script Output 
FAILED: Too many magical items 
FAILED: Too many magical items 
FAILED: Too many magical items 
Defined ::diamond ::ruby rings 


10.6.2 Static Methods II 


Like a class variable, a class (or static) method is one that is attached to the class definition, rather than 
to objects created from the class definition. Class methods are required to manipulate class variables 
and can be used to create factory methods if a class needs functionality that’s not easily handled with a 
normal constructor. 

As with the class variable, creating a class method requires determining the namespace in which 
the class definition is created. When this is known the forward command can be used to link the new 
command to the command created within the class definition namespace. 

The 00::Helpers namespace is a holder for new commands that can be evaluated within a con- 
structor or destructor. We can also create new commands in the 00: : define namespace to make them 
available to code in the class definition, but outside a method body. 

The next example shows the class variable example from the previous example, and adds a class 
method that will reduce the value of the quantity variable, allowing a new 1imitedItem to be 
created. 
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Example 29 


Script Example 
catch {limitedItem destroy} 


proc ::00::Helpers::classvar {args} { 
i## Get reference to class s namespace 
set nsCl [info object namespace [uplevel 1 {self class}]] 
set nsObj [Luplevel 1 {namespace current} ] 
# Link variables into local (caller’s) scope 
foreach v $args { 
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uplevel "my variable $v" 
upvar #0 ${nsCl}::$v ${nsObj}::$v 


proc ::00::define::classmethod {name {args ""} {body ""}} { 
## Create the method on the class if the caller gave 

d## arguments and body 

if {Lllength [info level 0]] == 4} { 

uplevel 1 [list self method $name $args $body ] 


} 

if Get the name of the class being defined 

set cls [Llindex [info level —1] 1] 

## Make connection to private class "my" command by 


## forwarding 
uplevel forward $name Linfo object namespace $cls]::my $name 


} 


00::class create limitedItem { 
constructor {} { 

classvar quantity 

# Initialize quantity the first time a limitedItem is created 

if {!Linfo exists quantity]} { 

set quantity 1 


} 
if {$quantity > 2} { 

error "Too many magical items" 
} 
incr quantity 

puts "Constructor [my varname quantity] — $quantity" 


} 
classmethod decreaseCount {} { 
variable quantity 
puts "Original quantity value is: $quantity" 
incr quantity —1 
puts "New quantity value is: $quantity" 


} 


limitedItem new 
limitedItem decreaseCount 


Script Output 
Constructor ::00::O0bj3::quantity — 2 
Original quantity value is: 2 
New quantity value is: 1 
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10.6.3 Aggregated Objects That Modify the Possessor 

Some subclasses have a permanent effect on the parent class, while others may only affect the parent 
class when their methods are evaluated. A subclass with a permanent effect can be merged into the 
parent class with a superclass or mixin relationship. An object that is only active when a method is 
invoked might be added as an aggregation. 

Our fantasy hero might possess some potions. These will have an effect when they are drunk, but 
do not affect the character’s attributes at other times. 

As described in the previous chapter, an aggregation can be implemented as a list of objects within 
an object. 

The uplevel and upvar commands can be used by methods of aggregated objects to modify 
variables in the parent’s object. 

Note that an aggregated object must have knowledge of the class that holds it if it is to directly 
modify variables in that class with upvar or uplevel. An alternative to this is to have the aggregated 
object return identifiers to the parent class and let the parent class apply them. 

The next example shows a character than can acquire potions and use them and a class of potions. 
Three techniques are demonstrated, using upvar, uplevel and returning values that can be used by 
the character class to modify the State. 

This character class has several methods: 

acquire Add an object to the list of possessions. 


FindItem Find an item by name and return the object identifier. 


use Invoke an object’s use method. 
drink Invoke an object’s drink method. 
apply Use the object’s app1y method to get the index and value and use these to modify 


that State parameter. 
The potion objects have a name to identify the potion, the name of a State array index that they 
modify and the amount of that modification. 
The potion class has four methods: 
getName Returns the identifier name. 


use Applies the potion using the up| evel command. 
drink Applies the potion using the upvar command. 
apply Returns the index and value for the parent class to use to 


modify the State. 
___ 


Example 30 
Script Example 


it Define a class that can acquire and 
## use potions 


o0o0::class create character { 
variable State 


10.6 Adding New Functionality to TclOO 


constructor {nm} { 


} 
# 


array set State {defense 2 attack 2 hitpoints 5} 
set State(name) $nm 
set State(possessions) {} 


Return the value of an element in the State 


method getParameter {param} { 


} 
# 


return $State($param) 


Add an object to the list of possessions 


method acquire {item} { 


} 


# 
# 


append State(possessions) $item 


nternal method to return an object with a 
name that matches the requested name 


method FindItem {name} { 


} 
i 


foreach item $State(possessions) { 
if {[$item getName] eq $name} { 
return $item 


} 


nvoke the requested items’s use method 


method use {name} { 


} 
it 


set item [my FindItem $name] 
item use 


nvoke the requested items’s drink method 


method drink {name} { 


} 
it 


set item [my FindItem $name] 
item drink State 


nvoke the requested items’s apply method 


method apply {name} { 


set item [my FindItem $name] 
assign [$item apply] index value 
incr State($index) $value 


———— 
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} 


i## Define a potion class 
00::class create potion { 


i# name: Name of the potion. 
jf attribute: The character’s attribute that is affected. 
i## modifier: The amount of effect on that attribute. 


variable name attribute modifier 


constructor {nm attr mod} { 
set name $nm 
set attribute $attr 
set modifier $mod 


jf Return a name 
method getName {} { 
return $name 


dt Apply a potion using the uplevel command 
method use {} { 
uplevel [list incr State($attribute) $modifier] 


i## Apply a potion using the upvar command 
method drink {varName} { 

upvar $varName localVar 

incr localVar($attribute) $modifier 


} 


## Return a potion’s attribute and modifier 
method apply {} { 
return [list $attribute $modifier] 
} 
} 


character create elmer Siegfried 

elmer acquire [potion new healing hitpoints 10] 
elmer acquire [potion new strength attack 2] 
elmer acquire [potion new dexterity defense 3] 


puts "Before healing potion: [elmer getParameter hitpoints ]" 
elmer use healing 
puts "After healing potion: [elmer getParameter hitpoints ]" 


10.6 Adding New Functionality to TclOO 315 


puts "Before strength potion: [elmer getParameter attack]" 
elmer drink strength 
puts "After strength potion: [elmer getParameter attack]" 


puts "Before dexterity potion: [elmer getParameter defense]" 
elmer apply dexterity 
puts "After dexterity potion: [elmer getParameter defense]" 


Script Output 
Before healing potion: 5 
After healing potion: 15 


Before strength potion: 2 
After strength potion: 4 


Before dexterity potion: 2 
After dexterity potion: 5 


4 Objects That Grow and Change 


Most objects have a static set of behavior throughout their lifetime. Other objects can be modeled 
better as having changed behaviors. For example, you might want to change the behavior of a Software 
Change Request when it evolves from being proposed, to accepted, to implemented, tested and finally 
released. 

The change of behavior can be accomplished by changing the object’s mixin class and thus chang- 
ing the methods. The mixin can be changed in the mainline code using the 00: :objdefine command, 
or within an object’s methods using the 00: :0bjdefine command and the se! f command to identify 
the object. 

The next example uses this technique to model an insect that spends four days as a caterpillar, two 
days as a pupae and finally emerges as a butterfly, lives for 3 days and perishes. 


_———_—aA_ 
Example 31 
Script Example 
00::class create bug { 
variable days; 
constructor {} { 
# Variable days will not exist unless initialized. 
set days 4 
00::objdefine [self] mixin larvae 


} 
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method day {} { 
[self] draw 
if {Lincr days —l1] <= 0} { 
[self] nextPhase 
} 


} 


00::class create butterfly { 
method draw {} { 
i## This method can access variable ‘days’ in parent class. 
variable days; 
puts "I am a butterfly — $days days left in this state" 
} 
method nextPhase {} { 
puts "My season in the sun is over" 
} 
} 


00::class create pupae { 
i## All methods can access variable ‘days’ in parent class. 
variable days; 
method draw {} { 
puts "I am a pupae — $days days left in this state" 


} 
method nextPhase {} { 

set days 3 

00::objdefine [self] mixin butterfly 
} 


} 


00::class create larvae { 
i## All methods can access variable ‘days’ in parent class. 
variable days; 
method draw {} { 
puts "I am a larvae — $days days left in this state" 


} 
method nextPhase {} { 

set days 2 

00::objdefine [self] mixin pupae 
} 


bug create myBug 
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for {set i O} {$i < 9} {incr 7} { 
myBug day 


Script Output 


I am a larvae — 4 days left in this state 
I am a larvae — 3 days left in this state 


I am a larvae — 2 days left in this state 

I am a larvae — 1 days left in this state 

I am a pupae — 2 days left in this state 

I am a pupae — 1 days left in this state 

I am a butterfly — 3 days left in this state 
I am a butterfly — 2 days left in this state 
I am a butterfly — 1 days left in this state 


My season in the sun is over 


7 BOTTOM LINE 


e TclOO can be used for rigidly defined class hierarchies or dynamically modified class environ- 
ments. 

¢ TclOO supports introspection into class inheritance and mixins, method argument and body, and 
the underlying namespace implementation of the TclOO package. 

e The 00::define and 00:objdefine commands let you modify a class or object at runtime. 

e The info class and info object commands provide information about a class or object. 

e The oo::define and 00::objdefine commands can accept either a single command and 
options, or a Tcl script with multiple commands and options. 

e When 00::define is used to modify a class all new and existing objects created from that class 
are modified. 

e When 00: :objdefine is used to modify an object, only that object is modified. 

e Methods can be modified with the method, filter, forward delete, export and rename 
subcommands. 

e Class hierarchy can be modified with the superclass and mixin subcommands. 

e Variables can be modified with the variable subcommand. 

e Static (or class) methods and variables can be created for TclOO classes using the se] f command 
or the 00: :Helpers namespace or a 00:: define: : NAME procedure. 

e The nextto command can be used to pass control directly to a given class’s method. 

e The info class command will provide information about a class. 

e The info object command will provide information about an object. 

e Information about methods and method chains is provided by the methods, methodtype, 
definition, filters, forward and cal] subcommands. 
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e Aclass hierarchy can be serialized using the info commands to create a set of commands to recreate 
the class structure. 

e An object can be introspected to create a set of commands to recreate the object. 

e A variable can be linked to a callback (like the trace) command with the my varname 
command. 

e A method can be linked to a callback (like an after event) with the sel f command. 

e The self class command returns the name of the class which contains the command. 


10.8 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range __ Description of Problems 


100-199 Short comprehension problems review material covered in the 
chapter. They can be answered in a few words or a 1-5-line script. 

These problems should each take under a minute to answer. 

200-299 These quick exercises require some thought or information beyond 
that covered in the chapter. They may require reading a man page or 
making a web search. A short script of 1-50 lines should fulfill the 
exercises, which may take 10-20 minutes each to complete. 

800-399 Long exercises may require reading other material or writing a few 
hundred lines of code. These exercises may take several hours to 
complete. 


e 100 What command will modify a TclOO class? 

e 101 What command will modify a TclOO object? 

e¢ 102 What command returns the list of a classes superclasses? 
e 103 What command adds a mixin to an object? 


e 104 Ifaclass has a superclass and needs to use the superclasses constructor, what command is 
used to transfer evaluation to the superclass constructor? 
Where is this command placed? 


e 105 1s a filter method evaluated before or after a non-filter method call? 
e 106 What command returns a list of an object’s variables? 

e 107 What command adds a mixin to all of a class’s objects? 

e¢ 108 What command will add a method to a single object? 


e 109 What command will add a new method to all the objects of a particular class? 
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200 What types of inheritance are better served with a superclass? 
20] What types of inheritance are better served with a mixin? 
202 When is it appropriate to modify an object’s class? 


203 Write a class for an elevator. It should have methods to moveToFloor, openDoor, 
closeDoor and requestFloor, and variables to track the requested floors, the current floor, the 
state of the door and whether or not the elevator is moving. 


204 Write a base class with a variable named State and a method named disp1|ay which will 
display the State contents. Create a derived class that has methods to modify the State variable. 
Then create two separate objects and confirm that they each have their own State variables. 


205 For the previous exercise, extract the base class’s disp]ay method and put it into a separate 
class. Mix this class into the derived class and confirm that everything is working correctly. 


206 Use the 00: :objdefine command to add a filter to the previous class that will only allow 
the State variable to accept integer values. 


207 Write a class that has methods to perform addition or subtraction. Add a filter to limit the 
inputs and returns to positive integers. Trying to subtract 10 from 2 should return 0 instead of -8 


208 Modify the character class in section 10.6.3 so that a potion is destroyed after being 
consumed. 


300 Write a class that opens a file in write mode and has a method that will add a timestamp to a 
message and then write the timestamp and message to that file. Add a method to this class that will 
write a heartbeat message to the file every 10 seconds. Create an object from this class and 
confirm that requested messages and heartbeat messages all end up in the file. 


301 Modify the class described in exercise 203 to use the trace command to confirm that no 
illegal floors are added to the list of requested floors. Any number less than 0, or the number 13 
are illegal floors. If an illegal floor is requested, remove it from the list of requested floors. 


302 Create a class with a class variable that counts the number of objects of this class that have 
been created. The destructor will reduce this count. Add a class method to report the count. 
Create and destroy objects to confirm that the count is correct. 


303 Create two classes, author and book. The author class will have a single variable name. 
The book class will have two variables title and author. The author variable will contain the 
name of the object that has the author’s name. 


304 Create a class named 1 i brary that uses the aggregation technique to contain several books. 
Add methods so that a book can be searched for by author or title. 


CHAPTER 


Introduction to Tk Graphics 


Everyone knows the fun part about computer programming is the graphics. The Tk graphics package 
lets a Tcl programmer enjoy this fun too. Tk is a package of graphics widgets that provides the tools to 
build complete graphics applications. Tk supports the usual GUI widgets (such as buttons and menus), 
complex widgets (such as color and file selectors), and data display widgets (such as an editable text 
window and an interactive drawing canvas). 

The user interaction widgets include buttons, menus, scrollbars, sliders, pop-up messages, and text 
entry widgets. A script can display either text or graphics with the text and canvas widgets. Tk provides 
three algorithms, for controlling the layout of a display, and a widget for grouping widgets. 

Finally, if none of the standard widgets do what you want, the Tk package supports low-level tools 
at both the script and C API levels to build your own graphical widgets. You can create either simple 
standalone widgets (similar to those provided by Tcl), or you can combine the simple widgets into 
complex widgets, sometimes called compound widgets, or megawidgets. 

The Tk widgets are very configurable, with good default values for most settings. For many wid- 
gets, you can set your own background colors, foreground colors, and border widths. Some classes of 
widgets have special-purpose options such as font, line color, and behavior when selected. This chap- 
ter discusses some of the more frequently used options. Consult the on-line manual pages with your 
installation for a complete list of options supported with your version of Tcl/Tk. 

Like most GUI packages, the Tk package is geared toward event-driven programming. If you are 
already familiar with event-driven programming, skip to Section 11.1. If not, the following paragraphs 
will give you a quick overview of event-driven programming. 

Using traditional programming, your program watches for something to happen and then reacts to 
it. For instance, user interface code resembles the following. 


while {!Leof stdin]} { 
gets command 
switch command { 
"cmdl" {doCmd1} 
"cmd2" {doCmd2} 
default {unrecognized command} 
} 
} 


The user interface code will wait until a user types in a command and will then evaluate that 
command. Between commands, the program does nothing. While a command is being evaluated, the 
user interface is inactive. 


Tcl/Tk: A Developer’s Guide. DOI: 10.1016/B978-0-12-384717-1.00011-7 32 1 
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With event-driven programming there is an event loop that watches for events, and when an event 
occurs it invokes the procedure that was defined to handle that event. This event may be a button press, 
a clock event, or data becoming available on a channel. Whenever the program is not processing a user 
request, it is watching for events. In this case, the user interface pseudo-code resembles the following. 


REGISTER exit TO BE INVOKED UPON exitCondition 
REGISTER parseUserInput TO BE INVOKED UPON CarriageReturn 
REGISTER processButton TO BE INVOKED UPON ButtonPress 


With Tk, the details of registering procedures for events and running an event loop are handled 
largely behind the scenes. At the time you create a widget, you can register a procedure to be evaluated 
whenever the widget is selected, and the event loop simply runs whenever there is no other processing 
going on. 


11.1 CREATING A WIDGET 


The standard form for the command to create a Tk widget is as follows. 


Syntax: WidgetClass widgetName requiredArguments ?options? 


WidgetClass A widget type, such as button, label, 
scrollbar,ortk_chooseColor. 


widgetName The name for this widget. Must conform to the Tk 
naming conventions described in the next section. 

requiredArguments Some Tk widgets have required arguments. 

?options? Tk widgets support a large number of options that define 


the fonts, colors, actions to be taken when the widget is 
selected, etc. As with the other command options, these 
are defined as -keyword value pairs. 


For example, this line: 


label .hello —text "Hello, World." 


will create a label widget named . he] /0, with the text Hello, World. As part of creating a widget, 
Tcl creates a command with the same name as the widget. After the widget is created, your script 
can interact with the widget via this command. This is similar to the way the objects are created with 
TclOO. Tk widgets support commands for setting and retrieving configuration options, querying the 
widget for its current state, and other widget-specific commands such as scrolling the view, selecting 
items, and reporting selections. The | abe] in the preceding example will appear in the default window. 
When the wish interpreter starts, it creates a default window for graphics named “.”. 

The various Tk window creation commands (button, label, etc.) allocate machine resources and 
create the internal structures for a window, but do not display the window. In order to display a widget, 
a script needs to describe where and how the widget is to be displayed. This is done with a geometry 
manager. 

Tk supports three geometry manager commands: place, pack and grid. The grid command is 
one of the easiest to use. 
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This command will display the .hel1o label: 
grid .hello 


11.2 CONVENTIONS 


There are a few conventions for widgets supported by Tk. These conventions include naming con- 
ventions for widgets and colors, and the conventions for describing screen locations, sizes, and 
distances. 


11.2.1 Widget Naming Conventions 


The Tk graphics widgets are named in a tree fashion, similar to a file system or the naming convention 
for namespaces. Instead of the slash used to separate file names, widget and window names are sepa- 
rated by periods. Thus, the root window is named “.”, and a widget created in the root window could 
be named .widgetl. 

A widget or window name must start with a period and must be followed by a label. The label may 
start with a lowercase letter, digit, or punctuation mark (except a period). After the first character, other 
characters may be uppercase or lowercase letters, numbers, or punctuation marks (except periods). It 
is recommended that you use a lowercase letter to start the label. 

Some widgets can contain other widgets. In that case, the widget is identified by the complete name 
from the top dot to the referenced widget. Tk widgets must be named by absolute window path, not 
relative. Thus, if widget one contains widget two, which contains widget three, you would access 
the last widget as .one.two.three. 

A widget path name must be unique. You can have multiple widgets named .widget1 if they 
are contained in different widgets (e.g., .main.widget1 and .subwin.widget1l are two different 
widgets). 


11.2.2 Color Naming Conventions 


Colors may be declared by name (red, green, lavender, and so on) or with a hexadecimal representation 
of the red/green/blue intensities. The hexadecimal representation starts with the # character, followed 
by 3, 6, 9, or 12 hexadecimal digits. The number of digits used to define a color must be a multiple 
of 3. The number will be split into three hexadecimal values, with an equal number of digits in each 
value, and assigned to the red, green, and blue color intensities in that order. The intensities range from 
0 (black) to OxF, OxFF, OxFFF, or OxFFFF (full brightness), depending on the number of digits used 
to define the colors. Thus, #00 (bright red, no green, no blue) creates deep red, #aa02dd (medium 
red, dim green, medium blue) creates purple, and #f ff feeee0000 (bright red, bright green, no blue) 
creates a golden yellow. 


11.2.3 Dimension Conventions 


The size or location of a Tk object is given as a number followed by an optional unit identifier. The 
numeric value is maintained as a floating-point value. Even pixels can be described as fractions. If 
there is no unit identifier, the numeric value defaults to pixels. You can describe a size or location in 
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inches, millimeters, centimeters, or points (1/72 of an inch) by using the unit identifiers shown in the 


following examples. 


Unit Identifier Meaning 


15.3 15.3 pixels 

aya 1-1/2 inches 

10m 10 millimeters (1 cm) 
Lede 1.3 centimeters (13 mm) 
90p 90 points (1-1/4 inches) 


11.3 COMMON OPTIONS 


The Tk widgets support many display and action options. Fortunately, these options have reasonable 
default values associated with them. Thus, you do not need to define every option for every widget 


you use. 


The following are some common options supported by many Tk widgets. They are described here, 
rather than with each widget that supports these options. Widget-specific options are defined under 
individual widget discussions. The complete list of options and descriptions is found in the Tcl/Tk 


on-line documentation under options. 


-background color 
-borderwidth width 


-font fontDescriptor 


-foreground color 


-height number 
-highlightbackground color 


-highlightcolor color 


-padx number 
-pady number 


-relief condition 


The background color for a widget. 


The width of the border to be drawn around widgets 
with 3D effects. 


The font to use for widgets that display text. Fonts 
are further discussed in Chapter 12, in regard to the 
canvas widget. 


The foreground color for a widget. This is the color 
in which text will be drawn in a text widget or 
on a label. It accepts the same color names and 
descriptions as -background. 


The requested height of the widget in pixels. 


The color rectangle to draw around a widget when 
the widget does not have input focus. 


The color rectangle to draw around a widget when 
the widget has input focus. 


The -padx and -pady options request extra space 
(in pixels) to be placed around the widgets when 
they are arranged in another widget or in the main 
window. 

The 3D relief for this widget: condition may 
be raised, sunken, flat, ridge, solid, or 
groove. 
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-text text The text to display in this widget. 


-textvariable varName The name of a variable to associate with this widget. 
The content of the variable will reflect the content of 
the widget. For example, the textvariable associ- 
ated with an entry widget will contain the characters 
typed into the entry widget. 


-width number The requested width of the widget in pixels. 


11.4 DETERMINING AND SETTING OPTIONS 


The value of an option can be set when a widget is created, or it can be queried and modified after the 
widget is created using the cget and configure commands. The cget subcommand will return the 
current value of a widget option. 
Syntax: widgetName cget option 
Return the value of a widget option. 


widgetName The name of this widget. 
cget Return the value of a single configuration option. 
option The name of the option to return the value of. 


——— rho 
Example 1 


Script Example 


button .exit_button —text "QUIT" —command exit 
puts "The exit button text is: [.exit_button cget —text]" 
puts "The exit button text color is: [.exit_button cget —foreground]" 


Script Output 


The exit button text is: QUIT 
The exit button text color is: Black 


The configure subcommand will return the value of a single configuration option, return all 
configuration options available for a widget, or allow you to set one or more configuration options. 
Syntax: widgetName configure ?optl? ?vall? ... ?optN? ?valN? 


widgetName The widget being set/queried. 


configure Return or set configuration values. 
?optx*? The first option to set/query. 
?valx*? An optional value to assign to this option. 


If configure is evaluated with a single option, it returns a list consisting of the option name, the 
name and class that can be used to define this option in the windowing system resource file, the default 
value for the option, and the current value for the option. 
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eee 
Example 2 


Script Example 


button .exit-button —text "QUIT" —command exit 

puts "The exit button text is: [.exit_button configure —text]" 
puts "The exit button text color is:" 

puts " [.exit_button configure —foreground] 


Script Output 


The exit button text is: —text text Text {} QUIT 
The exit button text color is: 
—foreground foreground Foreground Black Black 


If configure is evaluated with no options, a list of lists of available option names and values is 
returned. 


OOOO —_”——n—n— ay» >= 
Example 3 
Script Example 


button .exit_button -text "QUIT" -command exit 
puts [L.exit_button configure] 


Script Output 


{-activebackground activeBackground Foreground #ececec #ececec} 
{-activeforeground activeForeground Background Black Black} 
{—anchor anchor Anchor center center} 

{—background background Background #d9d9d9 #d9d9d9} 

{—bd —borderwidth} 

{-—bg —background} 

{—bitmap bitmap Bitmap {} {}} 

{—borderwidth borderWidth BorderWidth 2 2} 

{—command command Command {} exit} 

{—cursor cursor Cursor {} {}} 

{-default default Default disabled disabled} 
{-disabledforeground disabledForeground DisabledForeground #a3a3a3 #a3a3a3} 
{-fg —foreground} 

{-—font font Font {Helvetica —12 bold} {Helvetica —12 bold} 
{-—foreground foreground Foreground Black Black} 

{-height height Height 0 0} 

{-highlightbackground highlightBackground HighlightBackground #d9d9d9 #d9d9d9} 
{-highlightcolor highlightColor HighlightColor Black Black} 
{-highlightthickness highlightThickness HighlightThickness 1 1} 
{-image image Image {} {}} 

{-justify justify Justify center center} 

{-padx padxX Pad 3m 3m} 
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{-—pady pady Pad 1m 1m} 

{-relief relief Relief raised raised} 
{-state state State normal normal} 
{—takefocus takeFocus TakeFocus {} {}} 
{—text text Text {} QUIT} 

{—textvariable textVariable Variable {} {}} 
{-underline underline Underline —1 —1} 
{—width width Width 0 0} 

{-wraplength wrapLength WrapLength 0 0 


If configure is evaluated with option value pairs, it will set the options to the defined values. 
The following example creates a button that uses the conf igure command to change its label when 
it is clicked. The - command option and grid command are discussed in detail later in this chapter. 


Example 4 
Script Example 


set clickButton [button .bl —text "Please Click Me" \ 
—command {.bl configure —text "I’ve been Clicked! "}] 
grid $clickButton 


Script Output 


Refore cli Pay j 
belo i A K 


Please Click Me I've been Clicked! 
|__| 


11.5 THE BASIC WIDGETS 


These basic widgets, as follows, are supported in the Tk 8.0 and later distributions. 
button A clickable button that may evaluate a command when it is selected. 


radiobutton A set of on/off buttons and labels, one of which may be selected. 
checkbutton A set of on/off buttons and labels, many of which may be selected. 


menubutton A button that displays a scrolldown menu when clicked. 

menu A holder for menu items. This is attached toa menubutton. 

listbox Creates a widget that displays a list of options, one or more of which may be 
selected. The listbox may be scrolled. 

entry A widget that can be used to accept a single line of textual input. 

label A widget with a single line of text in it. 

message A widget that may contain multiple lines of text. 

text A widget for displaying and optionally editing large bodies of text. 


canvas A drawing widget for displaying graphics and images. 
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scale A slider widget that can call a procedure when the selected value changes. 

scrollbar Attaches a scrollbar to widgets that support a scrollbar. Will call a procedure when 
the scrollbar is modified. 

frame A container widget to hold other widgets. 

labelframe A container widget with an optional border and label to hold other widgets. 

toplevel A window with all borders and decorations supplied by the Window manager. 


Release 8.5 added these basic widgets: 
panedwindow — Resizable windows that can hold other widgets. 
spinbox A widget to select one element from a list by cycling through the list. 


11.6 INTRODUCING WIDGETS: label, button, AND entry 


The label, button, and entry widgets are the easiest widgets to use. The |abe! widget simply 
displays a line of text, the button widget evaluates a Tcl script when it is selected, and the entry 
widget accepts user input. 

All Tcl widget creation commands return the name of the widget they create. A good coding 
technique is to save that name in a variable and access the widget through that variable rather than 
hard-coding the widget names in your code. 


11.6.1 The label Widget 
Syntax: label Jabe]Name ?optionl? ?option2? ... 
Create a label widget. 
labelName The name for this widget. 
option Valid options for 1 abel include: 
-font fontDescriptor Defines the font to use for this display. 
Font descriptors are discussed in the 
next chapter. 
-textvariable varName The name of a variable that contains 
the display text. 
-text displayText Text to display. If -textvariable is 
also used, the variable will be set to this 
value when the widget is created. 


Note that the options can be defined in any order in the following example. 


2.—__ A 
Example 5 
Script Example 
set txt [label .la —-relief raised —text \ 
"Labels can be configured with text"] 
grid $txt 
set var [label .1lb —textvariable label2Var —relief sunken] 
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grid $var 
set label2Var "Or by using a variable" 


Labels can be configured with text 


[Or by using a variable 


The button Widget 


The button widget will evaluate a script when a user clicks it with the mouse. The script may be 
any set of Tcl commands, including procedure calls. By default, a script attached to a widget will be 
evaluated in the global scope. The scope in which a widget’s - command script will be evaluated can 
be modified with the namespace current, namespace code or the TclOO sel f command. 


Syntax: button buttonName ?optionl? ?option2? 


Create a button widget. 
buttonName The name to be assigned to the widget. 
?options? Valid options for button include: 
-font fontDescr Defines the font to use for this button. Font 
descriptors are discussed in the next chapter. 


-command script A script to evaluate when the button is 
clicked. 


-text displayTxt The text that will appear in this button. A 
newline character (\n) can be embedded in 
this text to create multi-line buttons. 


The example shows two sets of code, one in global scope and one in a namespace. Each of these 
generate the same GUI with the same behavior. Note the use of namespace current, namespace 
code and the -textvariabl/e option in the second code example. 


:3—_—_>AA A a 
Example 6 
Script Example (Global Scope) 
set myLabel [label .11 -text "This is the beginning text"] 
set myButton [button .bl -text "click to modify label"\ 
-command \ 
"$myLabel configure -text {The Button was Clicked}" ] 
grid $myLabel 
grid $myButton 


Script Example (Within a namespace) 
namespace eval demo { 
variable labelText "This is the beginning text" 
set myLabel [label .11 \ 
-textvariable [namespace current]::labelText] 
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set myButton [button .bl -text "click to modify label"\ 
-command [namespace code \ 
{set labelText {The Button was Clicked}}] ] 
grid $myLabel 
grid $myButton 
} 


Script Output 


belOore K 


click to modify label 


click to modify label 


11.6.3 The entry Widget 

The entry widget allows a user to enter a string of data. This data can be longer than will fit in the 
widget’s displayed area. The widget will automatically scroll to display the last character typed and can 
be scrolled back and forth with the arrow keys or by attaching the widget to a scrollbar (scrollbars are 
discussed later in this chapter). The entry widget can be configured to reflect its content in a variable, 
or your script can query the widget for its content. 


Syntax: entry entryName ?options? 
Create an entry widget. 


entryName The name for this widget. 
?options? Valid options for 1 abe] include: 
-font fontDescriptor Defines the font to use for this display. Font 
descriptors are discussed in Section 10.4.5. 
-textvariable VarName The variable named here will be set to the 
value in the entry widget. 
-justify side Justify the input data to the left margin of the 


widget (for entering textual data) or the right 
margin (for entering numeric data). Values for 
this option are right and left. 


$$$ $$ 


Example 7 
Script Example 
set input [entry .el -textvariable inputval] 
set action [button .bl -text "Convert to UPPERCASE" \ 
-command {set inputval [string toupper $inputval ]} ] 
grid $input 
grid $action 
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Script Output 


tcl/tk is fun to use TCL/TK IS FUN TO USE 


Convert to UPPERCASE Convert to UPPERCASE 


Note that the button command in the Section 11.6.2 example was enclosed within quotes, whereas 
the command in the Section 11.6.3 example was enclosed within curly braces. In Section 11.6.2 we 
want the variable theLabe] to be replaced by the actual name of the widget when the button creation 
command is being evaluated. The command being bound to the button is: 


.la configure -text {The Button was Clicked} 


If our script changes the content of the variable theLabel after creating the button, the command 
will still configure the original widget it was linked to (.la), not the window now associated with 
$thelabel. In Section 11.6.3, we do not want the substitution to occur when the button is created; 
we want the substitution to occur when the button is clicked. When the command is placed within 
brackets, the command bound to the button is: 


set inputval [string toupper $inputval ] 


The variable $inputval will be replaced by the content of the inputval variable when the button 
is selected. If the command in Section 11.6.3 were enclosed in quotes, the command bound to the button 
would have been evaluated, $i nputval would be replaced by the current value (an empty string), and 
the command [string toupper ""] would be evaluated and replaced by an empty string. The 
command bound to the button would be: 


set inputval 


In this case, clicking the button would cause the entry field to be cleared. The script associated with 
a button can be arbitrarily long and complex. As a rule of thumb, if there are more than three or four 
commands in the script, or if you are mixing variables that need to be substituted at widget creation 
time and evaluation time, it is best to create a procedure for the script, and invoke that procedure with 
the button -command option. For example, you can make an application support multiple languages 
by using an associative array for a translation table. 


ooo —_:”—n— wy E-> 
Example 8 


Script Example 


array set english {Nom Name Rue Street} 
array set french {Name Nom Street Rue} 


grid [label .name -text Name] 
grid [label .street -text Street] 


button .translate -text "En Francais" -command { 
foreach w {.name .street} { 
$w configure -text $french([$w cget -text]) 
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} 
} 


grid .translate 
Script Output 


Before click 


Street 


En Francais En Francais 


You can also make the button change text and command when it is clicked, to translate back to 
English, but the command starts to get unwieldy. 


Ee 
Example 9 
Script Example 
array set english {Nom Name Rue Street "In English" "En Francais"} 
array set french {Name Nom Street Rue "En Francais" "In English"} 
grid [label .name —text Name] 
grid [label .street —text Street] 
button .translate —text "En Francais" —command { 
if {[string match [.translate cget —text] "En Francais" ]} { 
foreach w {.name .street .translate} { 
$w configure —text $french(L[$w cget —text]) 
} 
} else { 
foreach w {.name .street .translate} { 
$w configure —text $english([$w cget —text]) 
} 
} 
} 


grid .translate 
Script Output 


Nom 


Street Rue 


En Francais In English 


Using a procedure instead of coding the translation in-line simplifies the code and makes the 
application more maintainable. 
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eee 
Example 10 


Script Example 


proc translate {widgetList request} { 
if {Lstring match "En Francais" $request]} { 
upvar #0 french table 
} else { 
upvar #0 english table 
} 


foreach w $widgetList { 
$w configure —text $table(L$w cget —text]) 
} 
} 
array set english {Nom Name Rue Street} 
array set french {Name Nom Street Rue} 
grid [label .name —text Name] 
grid [label .street —text Street] 
button .convert —text "En Francais" —command \ 
{translate {.convert .name .street} [.convert cget —text]} 
grid .convert 


11. Using Namespaces or TclO0 with Widgets 


The label attached to a widget with the -textvariabl]e option or the script attached to a button with 
the -command option is mapped to items in the global scope. If the variable exists in a namespace or 
TclOO object, or the script should be evaluated within a namespace or as an object’s method, you need 
to add some extra information to let the interpreter know where the script to be evaluated exists. 


Using Namespace Scope with a Widget 


Tcl provides two hooks for accessing code within a namespace. 


e namespace current Returns the fully qualified path to the current namespace. 
¢ namespace code Wraps a script so that it will be evaluated in the current namespace. 


It’s easiest to link a -textvariable to a label or a procdure to a button with the namespace 
current command. 


Syntax: namespace current 
Returns the fully qualified name of the current namespace. 


OOOO nn — ay» >= 
Example 11 


Script Example 


namespace eval buttonSpace { 
proc makeButton {} { 
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button .b —text "Button" \ 
—command [namespace current]::buttonProc 

grid .b 

} 

proc buttonProc {} { 
puts "You clicked button .b" 

} 

} 


buttonSpace::makeButton 


sutton | 


You clicked button .b 


If you need to attach a more complex script to a button’s - command option, the namespace code 
command may be more appropriate. As a rule, if the script attached to a button is complex, it should 
probably be a procedure. 

In the next example, the command to modify the label’s textvariable is evaluated in the 
buttonSpace namespace, but not within any procedure. 


Syntax: namespace code script 
Wrap a script so that it will be evaluated in the current namespace. 


script A script to be evaluated in the current namespace at some 
future time. 


eee 
Example 12 


Script Example 


namespace eval guiDemo { 
variable varName "Original Value" 


proc makeButton {} { 
label .1 —textvar [namespace current]::varName 


button .b —text "Button" \ 
—command [namespace code {set varName "New Value"}] 


grid .1 
grid .b 
} 
} 


guiDemo: :makeButton 
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Script Output 


Before king Butto 


Original Value 


Button 


Using TclOO with a Widget 
TclOO supports commands similar to the names pace commands to attach an object variable or method 
to a Tk widget. The two commands are: 


Button 


e my varname Returns the fully qualified path to a variable. 
e self Returns the name of the the current object. 


The my varname command is used to link an object’s variable to a Tk widget with the 
textvariable command. This is similar to the namespace current command. 


Syntax: my varname variableName 
Returns the full namespace path to a named variable. 
variableName_ The simple variable name. 


Objects don’t normally need to know how they are named outside the object. An object can access 
other methods with the my methodName construct. However, in order to register a callback, the object 
needs to be able to register its name with the callback. 

The self command returns the name of the current object. This is used to invoke a method in the 
current object without needing to know the name of the object. The se] f command is used to register 
an object method using - command option for a button. 

The next example shows how to map an object variable to a label and an object method to a button. 


—— eee eee 
Example 13 


Script Example 


00::class create guiDemo { 
variable objectVar 


constructor {} { 
set objectVar “Before button is clicked" 
label .1 —textvar [namespace current]::objectVar 


button .b —text "Button" \ 
—command “[self] changeObjectVar" 
grid .1 
grid .b 
} 
method changeObjectVar {} { 

set objectVar “After button was clicked" 
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} 
} 


guiDemo new 


After button was clicked 


Button Button 


11.7 APPLICATION LAYOUT: GEOMETRY MANAGERS AND CONTAINER 
WIDGETS 


When Tk creates a new widget, it allocates machine resources and creates the internal structures for a 
window, but does not display the widget. The widget is displayed when a geometry manager command 
is invoked for the widget. 

Tk supports three geometry manager commands. 


place Low-level control with support for placing windows at specific locations. 
pack High-level control that places windows in the largest open space. 
grid High-level control that places windows in a grid arrangement. 


Simple applications can be created using just the top level windows and a geometry manager. More 
complex (i.e., most) applications require some level of grouping windows. 
Tk supports five container widgets that can be used to group windows. 


toplevel A new toplevel window that can contain other widgets. 

frame A simple container that holds other widgets within a toplevel 
window. 

labelframe A container window with optional label and outline that holds other 


widgets within a toplevel window. 


panedwindow A set of container windows that can be resized to show more or less 
of the windows they contain. 


ttk::notebook A tabbed notebook container widget. 


11.7.1 Container Widgets: frame, labelframe, panedwindow 


You frequently need to group a set of widgets when you are designing a display. For instance, you will 
probably want all buttons placed near each other, and all results displayed as a group. 

The Tk container widgets range from the basic frame that holds other widgets to the toplevel 
that provides a complete new application level window. 

You can place any widget (including more container widgets) into any of these container widgets, 
nesting the window hierarchy as deeply as the application requires. 
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The frame Widget 

The basic Tk widget for grouping other widgets is frame. The frame widget is a rectangular container 
widget that groups other widgets. You can define the height and width of a frame or let it automatically 
size itself to fit the content. 


Syntax: frame frameName ?options? 
Create a frame widget. 
frameName The name for the frame being created. 
?options? The options for a frame include: 
-height numPixels Height (using units, as described in Section 11.2.3). 
-width numPixels Width (using units, as described in Section 11.2.3). 
-background color The color of the background (see Section 11.2.2). 


-relief value Defines how to draw the widget edges. Can make the 
frame look raised, sunken, outlined, or flat. The value 
may be one of sunken, raised, ridge, or flat. 
The default is f 1 at, to display no borders. 


-borderwidth width Sets the width of the decorative borders. The width 
value may be any valid size value (as described in 
Section 11.2.3). 


A display can be divided into frames by functionality. For example, an application that inter- 
faces with a database would have an area for the user to enter query fields, an area with the 
database displays, an area of buttons to generate searches, and so on. This could be broken 
down into three primary frames: .entryFrame, .displayFrame, and .buttonFrame. Within 
each of these frames would be the other widgets, with names such as .entryFrame.userName, 
.displayFrame.securityRating, and .buttonFrame.search. 

The next example shows a common application layout with a basic information frame at the top, 
a set of action buttons, a main area with the application and a bottom status line. The frame names 
are assigned to variables, and the variable names are used to create widgets within the frames. This 
technique makes it easier to pick up sections of a GUI and rearrange them. 


_=———_—aA 
Example 14 
Script Example 

set infoFrame [frame .info] 

set buttonFrame [frame .buttons] 

set mainFrame [frame .main —relief solid —borderwidth 2] 

set statusFrame [frame .status] 


set w Llabe infoFrame.name —text "Sample Application" \ 
—font {arial 16 bold}] 
grid $w 


foFrame.version —text "Revision 1.0"] 


= 


set w [labe 
grid $w 
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foreach buttonName {File Edit Help} { 
lappend buttonList [button $buttonFrame.b_-$buttonName \ 
—text $buttonName —command "perform_$buttonName" ] 


} 
grid {*x}$buttonList 


foreach id {Name Street City State} { 
set wl [label $mainFrame.1_$id —text $id: ] 
set w2 Lentry $mainFrame.e_$id —textvariable State($id) \ 
—background white] 
grid $wl $w2 


set wl [label $statusFrame.status —textvariable status] 
set w2 [label $statusFrame.time —textvariable time] 


grid $wl $w2 


set status "No Errors" 
set time [clock format [clock seconds]] 


grid $infoFrame 
grid $buttonFrame —sticky w 
grid $mainFrame —sticky ew 
grid $statusFrame 

Script Output 


Sample Application 


Revision 1.0 


Edit Help 


No Eritars Sui jul Os Iss3il ss} Eby 20 


The previous example uses the -relief option to make the main frame stand out from the other 
frames. You can modify the background color and the outline for frames, but there is very little 
else that you can do to affect the appearance of an application with just a frame. The 1 abel frame, 
panedwindow and ttk: :notebook widgets allow more control over the applications appearance. 
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The label frame Widget 
The | abel frame widget provides the functionality of the frame widget with a border and a label. The 
labelframe can be used to hold a single widget, or a set of widgets. 


Syntax: labelframe frameName ?options? 
Create a label frame widget. 
frameName The name for the 1 abel frame being created. 
?options? The options for a label frame include: 
-background color A background color, or an empty string. If the back- 


ground is an empty string the windows behind the 
frame can show through. 


-text string Text to display as this widget’s label. 
-labelanchor location Where to display the label. May be one of: nw, n, 
ne, e, Se, S, SW, Or W. 


The next example revisits the previous example, except that instead of label/entry pairs for the input 
fields it uses some labelframes. 


——————————————— eee ee ee eee 
Example 15 


Script Example 


set infoFrame [frame .info] 

set buttonFrame [frame .buttons] 

set mainFrame [frame .main —relief solid —borderwidth 2] 

set statusFrame [frame .status] 

set w Llabe infoFrame.name —text "Sample Application" \ 
—font {arial 16 bold}] 

grid $w 

set w [labe infoFrame.version —text "Revision 1.0"] 

grid $w 


foreach buttonName {File Edit Help} { 
append buttonList [button $buttonFrame.b_$buttonName \ 
—text $buttonName —command "perform_$buttonName" ] 


} 


grid {*}$buttonList 


foreach id {Name Street City State} { 
set w Llabelframe $mainFrame.1_$id —text $id: ] 
set w2 Lentry $w.e_$id —textvariable State($id) \ 
—background white ] 
grid $w 
grid $w2 
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set wl [label $statusFrame.status —textvariable status] 
set w2 [label $statusFrame.time —textvariable time] 


grid $wl $w2 


set status "No Errors" 
set time [clock format [clock seconds]] 


d $infoFrame 

grid $buttonFrame —sticky w 
id $mainFrame —sticky ew 
d $statusFrame 


Sample Application 


Revision 1.0 


Edit Help 


No Errors Sun Jul 03 17:42:07 EDT 2011 


The ttk: :notebook Widget 
Some applications have multiple windows in which the individual window is a self-contained entity. 
The tabbed browsers are a common example of this. 

The notebook widget was introduced with the Themed ToolKit widgets in the 8.5 release. The 
ttk widgets provide a more native look and feel on Mac and Windows platforms and add several 
new widgets to Tk. Unlike the standard Tk widgets, the ttk widgets are developed in a private ttk 
namespace. 


Syntax: ttk::notebook widgetName ?-option value? 
Creates a notebook widget which can contain multiple tabs. 
widgetName Thename of this widget following the normal Tk naming conventions. 
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?-option? Options to control how the notebook appears. 


?-height? If greater than 0, this specifies the height of the notebook page 
area. The default is to use the largest height of windows that have 
been added to the notebook. 


When you create a notebook, Tk also creates a new command with the same name as the note- 
book. You can use this command to control the notebook. The notebook command supports two 
subcommands: 

add Add a new tab as the last tab in the set of tabs. 


insert Add anew tab at a specific location in the set of tabs. 
Syntax: notebookName add window ?-option value? 


notebookName insert position window ?-option value? 
Add a new tab to the set of tabs. 
window The window to add to the notebook. 
position For insert, this is the location in the list of tabs to add the new tab. 
-option Options to control how the tab is added. There are several options 
including: 
?-text? The text to display in the tab. 
?-image? Animage to display in the tab. 
?-sticky? One or more of n, e, s or w. This specifies how the new window 


should be placed within the notebook page. The default is to 
center the new window. 


To use the notebook: 


Create a notebook widget with the ttk: :notebook command. 

Create a frame to hold the widgets that will be shown in a tab. 

Add the frame to the notebook, supplying some text to display in the tab. 
Create widgets within the frame that was added to the notebook. 


Pen 


If a notebook page will only have a single widget displayed (perhaps a text or canvas widget), you 
can skip creating the frame. For notebook pages with multiple widgets, it’s best to provide a frame or 
label frame to hold them. 

The next example shows building the mainFrame portion of the previous example for more infor- 
mation. The nested lists are used to create the three tabs and the widgets inside the notebook pages. 
Rather than try to create human-readable names for the widgets, the uni que value is incremented each 
time a new window is created. This technique is useful when a GUI is being constructed from a set of 
data, rather than coding each window name individually. 


OOOO.” —n—n—n— aay» 
Example 16 


Script Example 


i## Define a unique number to create an undefined 
i## number of unique widget names 
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set unique 0 


if Create the notebook and grid it in the main frame 
set note [::ttk::notebook $mainFrame.n] 


grid $note 


if Nested lists for the 3 tabs and the elements within 


if each tab. 


foreach txt {Address Biographical Employment} \ 


e 


set w [ 
foreach 


ements { {Street City State} 
{Name {Birth} {School }} 
{{Start Date} {End Date}} } { 
frame $note.f_Lincr unique] ] 
el $elements { 


set wl Llabelframe $w.1f_Lincr unique] —text $el] 
set w2 [entry $wl.e_Lincr unique] —textvar State($el)] 
grid $wl 
grid $w2 

} 

$note add $w —text $txt —sticky n 

} 
Script Output 


Sample Application 


Revision 1.0 


File | Edit | Help 


Address | Biographical | Employment 


Street 


Sample Application 


Revision 1.0 
Edit | 


File Help File | 


Address | Biographical Employment | 
-Name 


— 


- 


Birth —— = 


Sample Application 


Address | Biographical Employment | 
Start Date 


-End Date — 


State 


o Errors Sun Jul 03 20:17:12 EDT 2011 


School 


o Errors Sun Jul 03 20:30:41 EDT 2011 


The panedwindow Widget 


A common GUI style is to have one or more windows that can be resized at the expense of other 
windows. This is particularly common with applications that have a large canvas or text widget and 
another window of information about the primary window. The TclTutor application on the website 
has three resizeable text windows to allow the user to decide how much screen real estate they want to 


devote to the lesson text, example or example output. 


The panedwindow widget is a container widget that can show multiple windows with a space 
main window for a resize sash. When the mouse passes over the resize area the cursor is 
modified to show that resizing is active. When the cursor shows resizing is active, a left-mouse-drag 


between each 


operation will resize the two windows adjacent to the sash area. 


o Errors Sun Jul 03 20:30:41 EDT 2011 
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As with the ttk: :notebook widget, the widgets added to the panedwindow widget can be frames 
containing more widgets or single widgets such as a text widget, canvas or listbox. 


Syntax: panedwindow windowName ?-option value? 
Create a panedwindow widget that can hold multiple widgets. 
-option The panedwindow widget supports several options including: 
-orient May be vertical or horizontal. The default is to 
arrange the widgets horizontally. 
-showhandle If true, a handle is displayed between the resizable 
windows. Default is false. 


-handlepad A numeric value to define how far from the top or left 
edge of the sash area to draw the handle. 


The panedwindow has an add command for adding windows to the pane. This command defaults 
to adding a window in the last position, but can also insert a window before or after a currently 
displayed window. 


Syntax: panedWindowName add widgetName ?-option value? ?widgetName...? 
Add one or more widgets to a panedwindow widget. 


panedWindowName The name of the paned window to have new windows added. 
This is the value returned by the panedwindow command. 


-option The add command supports several options including: 


-after widgetName Place the new window after the named win- 
dow. 


-before widgetName Place the new window before the named win- 
dow. 


The next example uses a panedwindow instead of three notebook tabs to display the three input 
areas. By default, each of the entry areas would be fully displayed, but the application window has 
been shrunk to show the sash being used to resize the windows. 


ooo ——_” nnn — wy z= 
Example 17 


i## Create the paned window and grid it in the main frame 
set pw Lpanedwindow $mainFrame.n] 
grid $pw 


if Nested lists for the 3 tabs and the elements within 
if each tab. 


foreach txt {Address Biographical Employment} \ 
elements { {Street City State} 
{Name {Birth} {School }} 
{{Start Date} {End Date}} } { 
set w [frame $pw.f_Lincr unique] —relief solid —borderwidth 1] 
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foreach el $elements { 
set wl [Llabelframe $w.1f_Lincr unique] —text $el] 
set w2 [entry $wl.e-Lincr unique] —textvar State($el)] 
grid $wl 
grid $w2 

} 

$pw add $w 

} 


Script Output 
Sample Application 


Revision 1.0 


Sample Application 


Revision 1.0 


File | Edit | Help | 


File | Edit | Help | 


Start Date 


End Date | 


No Errors Mon Jul 04 12:58:20 EDT 2011 


No Errors Mon Jul 04 12:58:20 EDT 2011 


11.7.2 Widget Layout: place, pack, and grid 

Stacking one widget atop another is useful for extremely simple examples, but real-world applications 
need a bit more structure. Tk includes three layout managers (place, pack, and grid) to give you 
control over your application interface. 

The layout managers allow you to describe how the widgets in your application should be arranged. 
The layout managers use different algorithms for describing how a set of widgets should be arranged. 
Thus, the options supported by the managers have little overlap. 

All of the window managers support the - in option, which defines the window in which a widget 
should be displayed. By default, a widget will be displayed in its immediate parent widget. For exam- 
ple, a button named .mainButton would be packed in the root (.) window, whereas a button named 
.buttonFrame.controls.offButton would default to being displayed in the. controls widget, 
which is displayed in the .buttonFrame widget. 

Using the tree-style naming conventions and default display parent for widgets makes code easier to 
read. This technique documents the widget hierarchy in the widget name. However, the default display 
parent can be overridden with the - in option if your program requires this control. 


The place Layout Manager 

The place command lets you declare precisely where a widget should appear in the display window. 
This location can be declared as an absolute location or a relative location based on the size of the 
window. Applications that use few widgets or need precise control are easily programmed with the 
place layout manager, and the place layout manager is useful to display a window (like an alert) 
over other windows. 
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For most applications, however, the place layout manager requires too much programmer over- 
head and makes an application that doesn’t look correct after resizing. The pack and grid managers 
are recommended as general-use layout managers. 


Syntax: place widgetName option ?options? 
Declare the location of a widget in the display. 
widgetName The name of the widget being placed. 


option The place command requires at least one X/Y pair of these 
placement options: 


-x xLocation 
-y yLocation An absolute location in pixels. 
-relx xFraction 


-rely yFraction A relative location given as a fraction of the distance across 
the window. 


-inwindowName A window to hold this widget. The window windowName 
must be either the immediate parent or lower in the window 
hierarchy than the window being placed. That is, for exam- 
ple, Window .framel.frame2.label can be placed -in 
.framel.frame2 or framel.frame2.frame3.frame4, 
but not . framel. 


The following example uses the place command to build a simple application that calculates a 
15% sales tax on purchases. As you can see, there is a lot of overhead in placing the widgets. You need 
a good idea of how large widgets will be, how large your window is, and so on, in order to make a 
pretty screen. 


———————————— eee eee 
Example 18 
Script Example 


i## Create the "quit" and "calculate" buttons 
set quitbutton [button .quitbutton —text "Quit" —command "exit" ] 


set gobutton [button .gobutton —text "Calculate Sales Tax" \ 


—command {set salesTax [format %.2f [expr $userInput * 0.15] ]}] 


i## Create the label prompt, and entry widgets 
set input [entry .input —textvariable userInput] 
set prompt [label .prompt —text "Base Price:"] 


if Create the label and result widgets 
set tax Llabel .tax —text "Tax :"] 
set result [label .result —textvariable salesTax —relief raised] 


if Set the size of the main window 
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. configure —width 250 —height 100 


ar 


Place the buttons near the bottom 
ace $quitbutton —relx .75 -rely .7 
ace $gobutton —relx .01 -rely .7 


0 OU 


i## Place the input widget near the top. 
place $prompt —x 0 -y 0 
place $input —x 75 -y 0 


if Place the results widgets in the middle 
place $tax —x 0 —y 30 
place $result —x 40 —y 30 


Script Output 


Calculate Sales Tax Quit 


The pack Layout Manager 
The pack command is quite a bit easier to use than pl ace. With the pack command, you declare the 
positions of widgets relative to each other and let the pack command worry about the details. 


Syntax: pack widgetName ?options? 
Place and display the widget in the display window. 
widgetName ‘The widget to be displayed. 


?options? The pack command has many options. The following 
options are the most used: 


-side side Declares that this widget should be packed closest 
to a given side of the parent window. The side 
argument may be one of top, bottom, left, or 
right. The default is top. 


-anchor edge If the space assigned to this widget is larger than the 
widget, the widget will be anchored to this edge of 
the space. The space parameter may be one of n, 
S, @, OrW. 

-expand boolean Ifsetto 1 or yes, the widget will be expanded to fill 
available space in the parent window. The default is 
0: (do not expand to fill the space). The boolean 
argument may be one of 1, yes, 0, orno. 

-fill direction Defines whether a widget may expand to fill extra 
space in its parcel. The default is none (do not fill 
extra space). The di rection argument may be: 
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none Donot fill 


Xx Fill horizontally 
y Fill vertically 
both Fill both horizontally and vertically 
-padx number Declares how many pixels to leave as a gap 


between widgets. 


-pady number Declares how many pixels to leave as a gap 
between widgets. 


-after widgetName Pack this widget after (on top of) widget Name. 


The packer can be conceptualized as starting with a large open square. As it receives windows 
to pack, it places them on the requested edge of the remaining open space. For example, if the first 
window is a label with the -side left option set, pack would place the left edge of the label against 
the left side of the empty frame. The left edge of the empty space is now the right edge of the label, 
even though there may be empty space above and below this widget. 

If the next item is to be packed -side top, it will be placed above and to the right of the first 
widget. The following code shows how these two widgets would appear. Note that even though the 
anchor on the top label is set to west, it only goes as far to the west as the east-most edge of the first 
widget packed. 


_——_$_—_—-—_ 
Example 19 
Script Example 
label .la —background gray80 —text LEFT —relief solid 
label .1b —background gray80 —text TOP —relief solid 
pack .la —side left 
pack .1b —side top —anchor w 
. configure —background white —relief solid —borderwidth 3 
if wm interacts with the window manager — discussed later 
## this command makes the window smaller 
wm geometry . 80x50 


Script Output 
TOP 


LEFT 


The pack algorithm works by allocating a rectangular parcel of display space and filling it in a given 
direction. If a widget does not require all available space in a given dimension, the parent widget will 
“show through” unless the - expand or - fi11 option is used. 

The following example shows how a label widget will be packed with a frame with various combi- 
nations of the -fi11 and -expand options being used. The images show the steps as new frames are 
added to the display. 


348 CHAPTER 11 Introduction to Tk Graphics 


eee 
Example 20 


Script Example 


i## Create a root frame with a black background, and pack it. 
frame .root —background black 

pack .root 

i## Create a frame with two labels to allocate 2 labels worth of 
it vertical space. 

i## Note that the twoLabels frame shows through where the top 

i## label doesn’t fill. 

frame .root.twoLabels —background gray50 

label .root.twoLabels.upperLabel —text "twoLabels no fill top" 
label .root.twoLabels.lowerLabel —text "twoLabels no fill lower" 
pack .root.twoLabels —side left 

pack .root.twoLabels.upperLabel —side top 

pack .root.twoLabels.lowerLabel —side bottom 


twoLabels no fill topf] 


woLabels no fill lower 


i## Create a frame and label with no fill or expand options used. 
## Note that the .nofill frame is completely covered by the 

## label, and the root frame shows at the top and bottom 

frame .root.nofill —background gray50 

label .root.nofill.label —text "nofill, noexpand" 

pack .root.nofill —side left 

pack .root.nofill.label 


twoLabels no fill top 
nofill, noexpand 
woLabels no fill lower 


it Create a frame and label pair with the —fill option used when 
i## the frame is packed. 

i## In this case, the frame fills in the Y dimension to use all 

i## available space, and the label is packed at the top of 

if the frame. The .fill frame shows through below the label. 
frame .root.fill\_frame —background gray50 

label .root.fill\_frame.label —text "fill frame" 

pack .root.fill\_frame —side left —fill y 

pack .root.fill\_frame.label 


twoLabels no fill top Mil fi 


woLabels no fill lower 


i## Create a label that can fill, while the frame holding it will not. 
i## In this case, the frame is set to the size required to hold 

i## the widget, and the widget uses all that space. 

frame .root.fill\_label —background gray50 

label .root.fill\_label.label —text "fill label" 

pack .root.fill\_-label —side left 
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pack .root.fill\_label.label —fill y 


twoLabels no fill t fill f 
woLabels no fill top nofill, noexpand See Fill label 


woLabels no fill lower 


if Allow both the frame and widget to fill. 

i## The frame will fill the available space, 

## but the label will not expand to fill the frame. 
frame .root.fillBoth —background gray50 

label .root.fillBoth. label —text "fill label and frame" 
pack .root.fillBoth —side left —fill y 

pack .root.fillBoth.label —fill y 


twoLabel fill t fill f 
woLabels no fill top nofill, noexpand Fill label 


woLabels no fill lower 


i## Allow both the frame and widget to expand and fill. 

i## The —expand option allows the widget to expand into extra 
it space. 
## The —fill option allows the widget to fill the available 
## space. 
frame .root.expandFill —background gray50 

label .root.expandFill.label —text "expand and fill label and frame" 
pack .root.expandFill —side left —fill y —expand y 

pack .root.expandFill.label —fill y —expand y 


twoLabel fill t : fill f : fill label and f 
sie nofill, noexpand soe Fill label gee on ee Taine. expand and fill label and frame 


woLabels no fill lower 


The pack command is good at arranging widgets that will go in a line or need to fill a space 
efficiently. It is somewhat less intuitive when you are trying to create a complex display. The solution 
to this problem is to construct your display out of frames and use the pack command to arrange widgets 
within the frame, and again to arrange the frames within your display. For many applications, grouping 
widgets within a frame and then using the pack command is the easiest way to create the application. 
The following example shows a fairly common technique of making a frame to hold a 1abel prompt 
and an entry widget. 


-__ 
Example 21 
Script Example 

if Create the frames for the widgets 

set buttonFrame [frame .buttons] 

set inputFrame [frame .input] 

set resultFrame [frame .results] 


if Create the widgets 
set quitbutton [button .buttons.quitbutton —text "Quit" \ 
—command "exit" ] 
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set gobutton [button .buttons.gobutton \ 
—text "Calculate Sales Tax" \ 
—command {set salesTax [format %.2f [expr $userInput * 0.15] ]}] 
set input Lentry $inputFrame.input —textvariable userInput] 
set prompt [label $inputFrame.prompt —text "Base Price:"] 
set tax [label $resultFrame.tax —text "Tax :"] 
set result [label .results.result —textvariable salesTax \ 
—relief raised] 


if Pack the widgets into their frames. 
pack .buttons.quitbutton —side right 
pack .buttons.gobutton —side right 
pack $input —side right 
pack $prompt —side left 

] 


pack $tax —side left 
pack $result —side left 


if Pack the frames into the display window. 
pack .buttons —side bottom 
pac inputFrame —side top 


i## The left example image is created by setting 
i## withFill to 0 outside this code snippet. 
i## The right example image is created by setting 
i## withFill to 1 outside this code snippet. 
if {$withFill} { 

pack $resultFrame —after $inputFrame —fill x 
} else { 

pack $resultFrame —after $inputFrame 


} 
Script Output 
set withFill 0 
Base Price: |59.95 


Tabs 2|.98 


Base Price: [59.95 


ax: 89 


99 
Calculate Sales Tax Quit 


Calculate Sales Tax | Quit | 


Note the way the -side option is used in the previous example. The buttons are packed with 
-Side set to right. The pack command will place the first widget with a - side option set against 
the requested edge of the parent frame. Subsequent widgets will be placed as close to the requested 
side as possible without displacing a widget that previously requested that side of the frame. 

The -fill x option to the pack $resultFrame allows the frame that holds the $tax and 
$result widgets to expand to the entire width of the window, as shown in the set Withfill 1 
result. By default, a frame is only as big as it needs to be to contain its child widgets. Without the 
-fil1 option, the resultFrame would be the narrowest of the frames and would be packed in the 
center of the middle row, as shown in the set withfill 0 result. With the -f111 option set to fill 
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in the X dimension, the frame can expand to be as wide as the window that contains it, and the widgets 
packed on the left side of the frame will line up with the left edge of the window instead of lining up 
on the left edge of a small frame. If you want a set of widgets .a, .b, and .c to be lined up from left 
to right, you can pack them as follows. 


pack .a —side left 
pack .b —side left 
pack .c —side left 


The grid Layout Manager 
Many graphic layouts are conceptually grids. The grid layout manager is ideal for these types of 
applications, since it lets you declare that a widget should appear in a cell at a particular column and 
row. The Grid manager then determines how large columns and rows need to be to fit the various 
components. 
Syntax: grid widgetName ?widgetNames? option 

Place and display the widget in the display window. 

widgetName ‘The name of the widget to be displayed. 

?options? The grid command supports many options. The fol- 

lowing is a minimal set. 


-column number The column position for this widget. 

-row number The row for this widget. 

-columnspan number How many columns to use for this widget. Defaults 
to 1. 

-rowspan number How many rows to use for this widget. Defaults to 1. 

-sticky side Which edge of the cell this widget should “stick” to. 


Values may ben, s, e, w, or a combination of these 
letters (to stick to multiple sides). 

The -sticky option lets your script declare that a widget should “stick” to the north (top), south 
(bottom), east (right), or west (left) edge of the grid in which it is placed. By default, a widget is 
centered within its cell. Any of the options for the grid command can be reset after a widget is packed 
with the grid configure command. 

Syntax: grid configure widgetName -option optionValue 
Change one or more of the configuration options for a widget previously 
positioned with the grid command. 
widgetName The name of the widget to have a configuration option changed. 
-option ?value? The option and value to modify (or set). 


——— reson 
Example 22 


Script Example 


set quitbutton [button .quitbutton —text "Quit" —command "exit" ] 
set gobutton [button .gobutton —text "Calculate Sales Tax" \ 


352 CHAPTER 11 Int 


—command {set salesTax 
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[format %.2f [expr $userInput * 0.15] ]}] 


set input [entry .input —textvariable userInput ] 


set prompt [label .prompt —text "Base Price:"] 
set tax [label .tax —text "Tax :"] 
set result [label .result —textvariable salesTax —relief raised] 


grid $quitbutton $gobutton —row 3 


grid $prompt $input —row 1 


grid $tax $result —row 


Working Together 


The different layout manager: 


2 -s 


ticky w 


s can be used together to get the screen layout you desire. In the rules 


defined in the following, .f1 and. f2 are frames that contain other widgets. 

e Within a single frame, any single layout manager can be used. The following is valid. 
pack .fl.bl -side left 
grid .f2.b1 -column 1 -row 3 

e Within a single frame, the grid and pack cannot be mixed. The following is not valid. 
pack .fl.bl -side left 
grid .f1.b2 -column 1 -row 3 

e The place can be used with either the grid or pack command. The following is valid. 
pack .fl.bl -side left 
place .fl.label -x 25 -y 10 
grid .f2.b1 -column 1 -row 3 
place .f2.label -xrel .1 -yrel .5 

e Frames can be arranged with either grid or pack, regardless of which layout manager is used 
within the frame. The following is valid. 
pack .fl.bl -side left 
grid .f2.b1 -column 1 -row 3 
grid .f1 -column 0 -row 0 
grid .f2 -column 1 -row 0 


11.8 SELECTION WID 
listbox 


GETS: radiobutton, checkbutton, menu, AND 


Allowing the user to select one (or more) items from a list is a common program requirement. The 
Tk graphics extension provides the selection widgets radiobutton, checkbutton, menu, and 


listbox. 
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11.8.1 radiobutton and checkbutton 


The radiobutton and checkbutton widgets are very similar. The primary difference is that 
radiobutton will allow the user to select only one of the entries, whereas checkbutton will allow 
the user to select multiple items from the entries. 


radiobutton 
The radiobutton widget displays a label with a status indicator next to it. When a radiobutton is 
selected, the indicator changes color to show which item has been selected, and any previously selected 
radiobutton is deselected. 
Syntax: radiobutton radioName ?-options value? 
Create a radi obutton widget. 


radioName The name for this radiobutton widget. 
-option Options for the radiobutton include: 
-command script A script to evaluate when this button is clicked. 


-variable varName_ The variable defined here will contain the value of this 
button when the button is selected. If this option is used, 
the - value must also be used. 


-value value The value to assign to the variable. 


The -variable and - value options allow the radiobutton widget to be attached to a variable 
that will be set to a particular value when the button is selected. By using the - command option, you 
can assign a script that will be evaluated when the button is selected. If the - variable and -value 
options are also used, the script will be evaluated after the new value has been assigned to the widget 
variable. 

The following example shows how the magic shop in a computerized Fantasy Role Playing 
game can be modernized. Note the foreach {item cost} $itemList command. This style of the 
foreach command (using a list of variables instead of a single variable) was introduced in Tcl version 
7.4. It is useful when stepping through a list that consists of repeating fields, such as the name price 
name pricedatain itemList. 


— 
Example 23 
Script Example 
i## Update the displayed text in a label 
proc updateLabel {myLabel item} { 
global price 
$myLabel configure —text \ 
"The cost for a potion of $item is $price gold pieces" 


} 
i## Create and display a label 
set 1 [label .1 —text "Select a Potion"] 


grid $1 —column 0 —row 0 —columnspan 3 


# A list of potions and prices 
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set itemList [list "Cure Light Wounds" 16 \ 

"Boldness" 20 \ 

"See Invisible" 60] 

set position 0 

foreach {item cost} $itemList { 
radiobutton .b_-$position —text $item —variable price \ 

—value $cost —command [list updateLabel $1 $item] 

grid .b-$position —column $position —row 1 
incr position 


} 
Script Output 
e ion 


Select a Potion 


™ Cure Light Wounds Boldness ‘ See Invisible 


ing Boldne 
The cost for a potion of Boldness is 20 gold pieces 
“ Cure Light Wounds  Boldness ‘ See Invisible = 


All of the radiobutton widgets in this example share the global variable price. The variable 
assigned to the - variable option is used to group radiobutton widgets. For example, if you had 
two sets of radiobuttons, one for magic potions and one for magic scrolls, you would need to use 
two different variable names, such as potionPrice and scrol1Price. 

If you assign each radiobutton a different variable, the radiobuttons will be considered as 
separate groups. In this case, all buttons can be selected at once and cannot be deselected, since there 
would be no other button in their group to select. Note that the variable price is declared as a global 
in the procedure updateLabel. The variables attached to Tk widgets default to being in the global 
scope. 

The updateLabel procedure is called with an item name and uses the variable price to get the 
price. The $price value could be passed to the procedure by defining the - command argument as: 


-command [list updateLabel $1 $item $cost] 


This example used the variable for demonstration purposes. Either technique for getting the data to 
the procedure can be used. 


checkbutton 

The checkbutton widget allows multiple items to be selected. The checkbutton widget displays a 
label with a square status indicator next to it. When a checkbutton is selected, the indicator changes 
color to show which item has been selected. Any other checkbuttons are not affected. 

The checkbutton widget supports a - variable option, but unlike the case of radi obutton you 
must use a separate variable for each widget, instead of sharing a single variable among the widgets. 
Using a single variable will cause all buttons to select or deselect at once, instead of allowing you to 
select one or more buttons. 
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Syntax: checkbutton checkName ?options? 
Create a checkbutton widget. 
checkName The name for this checkbutton widget. 
?options? Valid options for the checkbutton widget include: 


-variable varName The variable defined here will contain the value 
of this button when the button is selected. 


-onvalue selectValue The value to assign to the variable when this 
button is selected. Defaults to 1. 


-offvalue nselectValue The value to assign to the variable when this 
button is not selected. Defaults to 0. 


————————OOO eee eee 
Example 24 


Script Example 


it Update the displayed text in a label 
proc updateLabel {myLabel item} { 
global price 
set total 0 
foreach potion [array names price] { 
incr total $price($potion) 


} 


$myLabel configure —text "Total cost is $total Gold Pieces 


} 


i## Create and display a label 
set 1 [label .1 —text "Select a Potion"] 
grid $1 —column 0 —row 0 —columnspan 3 


# A list of potions and prices 

set itemList [list "Cure Light Wounds" 16 \ 
"Boldness" 25 \ 
"See Invisible" 60 \ 
"Love Potion Number 9" 45 ] 


set position 


foreach {item cost} $itemList { 
checkbutton .b_$position —text $item \ 
—variable price($item) —onvalue $cost —offvalue 0 \ 
—command "[list updateLabel $1 $item]" 
grid .b_$position —row $position —column 0 —sticky w 
incr position 
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Script Output 
After Selecting 


Select a Potion 
| Cure Light Wounds 


otal cost is 41 Gold Pieces 
i Cure Light Wounds 


| Boldness i Boldness 


| See Invisible 


| See Invisible 


| Love Potion Number 9] |. Love Potion Number 9 


11.8.2 Pull-down Menus: menu, menubutton, and Menubars 


The Tk menu command creates the ubiquitous pull-down menu that we have all become so fond of. 
A Tk menu is an invisible holder widget that can be attached to a menubutton widget or used as a 
window ’s menu bar. The menubutton is similar to the button widget, described in Section 11.6. The 
differences include: 


e The default relief for a menubutton is flat, whereas a button is raised. 
e A menubutton can be attached to a menu instead of a script. 


Most of the examples that follow will use the -relief raised option to make the menubutton 
obvious. 
Syntax: menubutton buttonName ?options? 
Create a menubutton widget. 
buttonName The name for this menubutton. 


?options? The menubutton supports many options. Some of the 
more useful are: 


-text displayText The text to display on this button. 
-textvariable varName The variable that contains the text to be dis- 
played. 


-underline charPosition Selects a position for a hot key. 


-menu menuName The name of the menu widget associated with 
this menubutton. 


The -text and -textvariable options can be used to control the text displayed on a button. 
If a -textvariable option is declared, the button will display the content of that variable. If both 
a -text and -textvariable are defined, the -textvariable variable will be initialized to the 
argument of the - text option. 
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The -underline option lets you define a hot key to select a menu item. The argument to the 
-under1ine option is the position of a character in the displayed text. The character at that position 
will be underlined. If that character and the Alt key are pressed simultaneously, the menubutton will 
be selected. A menu widget is a invisible container widget that holds the menu entries to be displayed. 


Syntax: menu menuName ?options? 
Create a menu widget. 
menuName The name for this menu widget. Note that this name must be a child 
name to the parent menubutton. For example, if the menubutton 
is .fo0.bar, the menu name must resemble .foo.bar.baz. 
?options? The menu widget supports several options. A couple that are unique 
to this widget are: 


-postcommand script A script to evaluate just before a menu is posted. 


-tearoff boolean Allows (or disallows) a menu to be removed from the 
menubutton and displayed in a permanent window. 
This is enabled by default. 


Once a menu widget has been created, it can be manipulated via several widget subcommands. 
Those that will be used in these examples are as follows. 
Syntax: menuName add type ?-option val? 
Add a new menu entry to a menu. 


type The type for this entry. May be one of: 


separator A line that separates one set of menu entries from 
another. 
cascade Defines this entry as one that has another menu 


associated with it, to provide cascading menus. 
checkbutton Same as the standalone checkbutton widget. 
radiobutton Same as the standalone radiobutton widget. 
command Same as the standalone button widget. 
?-option? A few of the options that will be used in the examples 
are: 
-command script A script to evaluate when this entry is selected. 


-accelerator string Displays the string to the right of the menu entry as 
an accelerator. This action must be bound to an event. 
Binding is covered in Chapter 10. 


-label string The text to display in this menu entry. 


-menu menuName The menu associated with a cascade-type menu 
element. Valid only for cascading menus. 


-variable varName A variable to be set when this entry is selected. 


-value string The value to set in the associated variable. 
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-underline position The position of the character in the text for this menu 
item to underline and bind for action with this menu 
entry. This is equivalent to the - underline option 
the menubutton supports. 


AA 
Example 25 
Script Example 
i## Create a "Settings" menubutton 
menubutton .mb —menu .mb.mnu —text "Settings" \ 
—relief raised —background gray70 \ 
—menu .mb.mnu 
i## Add font selectors 
.mb.mnu add radiobutton —label "Large Font" \ 
—variable font —value {Times 18 bold} } 
.mb.mnu add radiobutton —label "Small Font" \ 
—variable font —value {Times 8 normal} 
grid .mb 


Large Fort 
Srnall Fort 


Alternatively, the command menuName insert can be used to insert items into a menu. This com- 
mand supports the same options as the add command. The insert command allows your script to 
define the position to insert this entry before. The insert and delete commands require an index 
option. An index may be specified in one of the following forms. 


number The position of the item in the menu. Zero is the topmost entry in the menu. 

end or last The bottom entry in the menu. If the menu has no entry, this is the same as 
none, 

active The entry currently active (selected). If no entry is selected, this is the same 
as none. 

@number The entry that contains (or is closest to) the Y coordinate defined by number. 


pattern The first entry with a label that matches the glob-style pattern. 
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Syntax: menuName insert index type ?options? 
Insert a new entry before position index. 
index The position to insert this entry before. 
type Type of menu item to insert. As described for add. 
?options? Options for this menu item. As described for add. 


In the following example, the Open selection will always be the first menu entry, and Exit will 
always be last. 


$A 
Example 26 
Script Example 
it Create a "Files" menu 
menubutton .mb —menu .mb.mnu —text "Files" \ 
—relief raised —background gray/70 
menu .mb.mn 
## Insert open and exit as first and last 
# selections 
-mb.mnu insert 0 command —label "Open" \ 
—command openFile\\ 
## .. Other menu entries... 
-mb.mnu insert end command —label "Exit" \ 
—command quitTask\\ 


A non-functional entry can be removed with the delete command or it could be configured as 
disabled with the entryconfigure command 


Syntax: menuName delete indexl index2 
Delete menu entries. 


indexl index2 Delete the entries between the numeric indices index1 and 
index2, inclusive. 
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Syntax: menuName entryconfigure index ?-option value? 
If no option, returns a list of all options and values. If no value, returns current 
setting for the option. If both option and value are specified, modify the option. 
index The index to query or modify. 
-option An option that can be set when using the add or insert 
command. 


sss gg 
Example 27 


Script Example 


menubutton .mb —menu .mb.mnu —text "Files" \ 
—relief raised —background gray/70 


menu .mb.mnu 
b.mnu insert 0 command —label "Open" \ 
—command openFile 


b.mnu add separator 


b.mnu add command —label "Save" \ 
—command saveData 


b.mnu add command —label "SaveAs" \ 
—command saveDataAs 
grid .mb 


i## If in demo mode, disable the Save options 


if {$demoMode} { 
.mb.mnu entryconfigure 3 —state disabled 
.mb.mnu entryconfigure 4 —state disabled 


} 


## ... In file open code. 

i## Check write permission on file. If not 

i## =«360writable, set ‘permission’ to 0, else l. 
oe. 


if Remove save option if no write permission 


if {!$permission} { 
.mb.mnu delete Save 


} 
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Script Output 


With no permission and in demoMode With permission and not demoMode 


BOO 
Files na 


Open 


age — A 
SaveAs 


The previous example knows that the Save and SaveAs entries are position 3 and 4. If your code 
can’t know that (perhaps menu entries are being added based on recent activity), it can learn the index 
of a menu entry based on a pattern with the index command. 


Syntax: menuName index pattern 
Return the numeric index of the menu entry with the label string. 


pattern An index pattern, as described previously. 


—_——— ee Oe 
Example 28 


Script Example 


menubutton .mb —menu .mb.mnu —text "Files" \ 
—relief raised 


menu .mb.mnu 
-mb.mnu add command —label Open 
-mb.mnu add separator 
foreach {label cmd} {Save saveCmd AutoSave autoSaveCmd \ 
SaveAs saveAsCmd} { 
.mb.mnu add command —label $label —command $cmd 


.mb.mnu add separator 


.mb.mnu add command —label Exit 


if ... much code. 
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if If running in demo mode, remove "Save" menu items’ 
if {$demoMode} { 

set first ~.mb.mnu index Save] 

i## Delete the first separator as well 

incr first —1 

set last [L.mb.mnu index SaveAs] 

-mb.mnu delete $first $last 


} 
grid .mb 
Script Output 
With demoMode == 1 


AutoSave 
SaveAs 


Exit 


The following example shows how the various menus are created and how they look in different 
versions of Tk. In actual fact, you cannot pull down all menus at once. You can, however, use the 


tear-off strip (select the dotted line at the top of the menus) to create a new window and have multiple 
windows displayed. 


= 


Example 29 
Script Example 
fl 


if Create a checkbutton menu — Place it on the left 
set checkButtonMenu [menubutton .mcheck \ 
—text "checkbuttons" —menu .mcheck.mnu] 
set checkMenu [menu $checkButtonMenu.mnu] 
grid $checkButtonMenu —row 0 —column 0 
$checkMenu add checkbutton —label “check 1" \ 
—variable checkButton(1) —onvalue 1 
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$checkMenu add checkbutton —label 


"check 2" \ 


—variable checkButton(2) —onvalue 2\\ 


dt 

if Create a radiobutton menu — P 

set radioButtonMenu [menubutton 
—text "radiobuttons" —menu 


ace it in the middle 


set radioMenu [menu $radioButtonMenu.mnu] 


grid $radioButtonMenu —row 0 —co 
$radioMenu add radiobutton —labe 
—variable radioButton —value 
$radioMenu add radiobutton —labe 
—variable radioButton —value 


-mradio \ 
radio.mnu] 
umn 1 

"radio 1" \ 
1 

"radio 2" \ 
2 


dt 
if Create a menu of mixed check, 
i## «menu separators 


radio, command, cascading and 


set mixButtonMenu Lmenubutton .mmix —text "mixedbuttons" \ 


—menu .mmix.mnu] 


set mixMenu [menu $mixButtonMenu. 


mnu] 


grid $mixButtonMenu —row 0 —column 2 


iF 


i## Two command menu entries\ 


$mixMenu add command —label "command 1" —command “doStuff 1" 
$mixMenu add command —label "command 2" —command “doStuff 2" 


i 


## A separator, and two radiobutton menu entries 


$mixMenu add separator 
$mixMenu add radiobutton —label 
—variable radioButton —value 
$mixMenu add radiobutton —label 
—variable radioButton —value 


radio 3" \ 
3 
radio 4" \ 
4 


vi 


i## A separator, and two checkbutton menu entries 


$mixMenu add separator 
$mixMenu add checkbutton —label 


check 3" \ 


—variable checkButton(3) —onvalue 3 
$mixMenu add checkbutton —label "check 4" \ 
—variable checkButton(4) —onvalue 4 


# 


i## A separator, a cascading menu, 


and two sub menus 
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i## within the cascading menu 
mixMenu add separator 
mixMenu add cascade —label "cascader" \ 
—menu $mixMenu.cascade 
enu $mixMenu.cascade 
mixMenu.cascade add command —label "Cascaded 1"\ 
—command "doStuff 3" 
mixMenu.cascade add command —label "Cascaded 2"\ 
—command "doStuff 4" 
i## Define a dummy proc for the command buttons to invoke. 
proc doStuff {args} { 
puts “doStuff called with: $args" 
} 


Script Output 
The widgets that are displayed will look like whatever is native on the platform where the application is running. These 
images are for Linux/X11 systems 
Tcl8.4 and earlier 
heckbuttons radiobuttons mixedbuttons 


[check 1 “~ radio 1 command 1 
[~ check 2 “ radio 2 command 2 


“ radio 3 
“ radio 4 


[check 3 
\ check 4 


cascader ~ Cascaded 1 
Cascaded 2 


heckbuttons radiobuttons mixedbuttons 


vy check 1 radio 1 | command 1 
check2 | radio2 | command 2 


+ radio 3 
radio 4 


vy check 3 
check 4 


cascader * Cascaded 1 
Cascaded 2 


Note that the radio buttons in this example all share the variable radi oButton, even though they 
are in separate menus. Selecting a radio item from the mixedbuttons window deselects an item 
selected in the radiobuttons menu. 
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Menubars 

A menu widget can be attached to a menubutton (as shown previously), can be designated as the 
menubar in a top-level window (such as the main window), or designated as a window created with 
the toplevel command (discussed in Section 11.11). The -menu option will designate a menu as a 
window’s menubar. 

A menubar will be displayed and implemented in a platform-specific manner. For example, when 
the script is evaluated on a Macintosh, the menubar of the window with focus will be displayed as the 
main screen menu. On an MS Windows or X Windows platform, the menubar will be displayed at the 
top of the window that owns the menubar. 


i## Add a menubar to the main window 

. configure —menu .menubar 

i## Create a new toplevel window with a menubar 
toplevel .top —menu .top.mnu 


Once a menubar has been created, new menu items can be added as with normal menus. 


ooo —-:.:—nmnmn— — aE 
Example 30 


Script Example 


. configure —menu .mbar 
i## Create the top menubar 
menu .mbar 


i## Add a Files pulldown menu to the menubar 

i## This appears at the left on all operating systems. 
.mbar add cascade —label Files —menu .mbar.files 

menu .mbar.files 

.mbar.files add command —label Open —command "openFile" 


i## Help shows up at the right on X11 based systems. 
-mbar add cascade —label Help —menu .mbar.help 

menu .mbar.help 
-mbar.help add command —label About —command "displayAbout" 


## Normal menu items appear in the order they are defined. 
.mbar add cascade —label Settings —menu .mbar.set 

menu .mbar.set 
-mbar.set add command —label Fonts —command "setFont" 


i## The .system menu appears on the icon under Windows systems 
-mbar add cascade —label System —menu .mbar.system 

menu .mbar.system 

.mbar.system add command —label "Windows System" 


## The .apple menu appears under the application menu 
.mbar add cascade —label Apple —menu .mbar.apple 
menu .mbar.apple 
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-mbar.apple add command —label "Apple Menu" 
-mbar add command —label Run —command "go" 


Files Settings System Apple Run 


Note that the Help menu is on the far right, even though it was the second menu added. Tcl supports 
some special naming conventions to access platform-specific conventions. The previous example was 
run on a Linux platform, so the .bar.help menu follows the X Window convention of placing Help 
on the far right. 


Name Platform Description 


.menubar.system MS Windows Adds items to the System menu. 


-menubar.help X Window Will make a right-justified Help menu. 
-menubar.help Macintosh Will add entries to the Apple Help menu. 
.menubar.apple Macintosh Items added to this menu will be the first 


items on the Apple menu. 


When the previous example is run on an MS Windows or Macintosh system, the special menus will 
be displayed, as shown in the following illustration. Note the (Tear-off) items in these menus. On 
X Window based systems, a menu can be turned into a top-level window by clicking the top (dotted) 
line. This line is referred to as the “Tear-off” line. You can inhibit creating this menu entry by creating 
the menu with the -tearoff 0 option. 

Under OS/X, the menubar.apple entries are added to the application menu. 


Apple Menu 


Services b 


Hide Wish 38H 
Hide Others “3H 
Show All 


Quit Wish #Q 


Under Windows, the menubar.system entries are added to the application menu attached to the 
icon. 
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Move 
Size 
Minimize 


Maximize 


Close Alt+F4 
(Tear-off) 
Windows System 


11.8.3 Selection Widgets: 1 istbox 


The 1istbox widget allows the user to select items from a list of items. The 1istbox widget can be 
configured to select one entry (similar to a radio button) or multiple entries, similar to a checkbutton. 

The 1istbox can be queried to return the positions of the selected items. This can be used to 
index into a list or array of information, or the 1 i stbox can be queried about the text displayed at that 
position. 

Syntax: listbox listboxName ?options? 

Create a 1istbox widget. 
listboxName The name for this 1istbox. 


?options? The listbox widget supports 
several options. Three useful 
options are: 


-selectmode style Sets the selection style for this 1istbox. The 
default mode is browse. This option may be set 
to one of: 

single Allows only a single entry to be selected. When- 


ever an entry is clicked, it is selected, and other 
selected entries are deselected. 


browse Allows only a single entry to be selected. When- 
ever an entry is clicked, it is selected, and other 
selected entries are deselected. When the cur- 
sor is dragged across entries with the left mouse 
button depressed, each entry will be selected 
when the cursor crosses onto it, and deselected 
when the cursor passes off. 


multiple Allows multiple entries to be selected. An 
entry is selected by clicking it (if not already 
selected). A selected entry can be deselected by 
clicking it. 
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extended Allows a single entry to be selected, or multiple 
contiguous entries to be selected by dragging 
the cursor over the entries. 


-exportselection bool If this is set true, the content of the listbox will 
be exported for other X11 tasks, and only a sin- 
gle listbox selection may be made. If you wish 
to use multiple 1istbox widgets with differ- 
ent selections, set this option to FALSE. This 
defaults to TRUE. 


-height numLines The height of this listbox in lines. 


When a 1istbox widget is created, it is empty. The 1istbox widget supports several commands 
for manipulating 1istbox content. The following are used in the chapters that follow. 


Syntax: ]istboxName insert index element ?elements? 
Inserts a new element into a 1istbox. 
index The position to insert this entry before. The word end causes 
this entry to be added after the last entry in the list. 


element A text string to be displayed in that position. This must be 
a single line. Embedded newline characters are printed as 
backslash-N, instead of generating a new line. 


oo 
Example 31 
Script Example 
i## Create and display an empty listbox 
listbox .1 —height 3 
grid .] 
it Add 3 elements to the listbox 
i## Note — insert at position 0 makes the display order the 
i## opposite of the insertion order. 
.l insert 0 first 
.l| insert 0 second 
.l insert 0 third 


Along with inserting elements into a listbox, you might need to delete one or more. The delete 
command will remove elements from a listbox. 
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Syntax: JistboxName delete first ?last? 
Delete entries from a 1 istbox. 


first The first entry to delete. If there is no last entry, only this entry 
will be deleted. 


last The last entry to delete. Ranges are deleted inclusively. 


————————— eee eee 
Example 32 


Script Example 


## Create and display an empty listbox 
listbox .1 —height 3 

pack .1 
## Add 3 elements to the listbox 

i## Note — insert at end position — order is as expected 
.l| insert end first 

.| insert end second 

.| insert end third 


if Delete the second listbox entry (count from 0) 
.1 delete 1 


Elements in a listbox can be selected by clicking on them. The curselection will return the 
element number that has been selected and the get command can be used to return the contents of a 
selected element 


Syntax: ]istboxName curselection 
Returns a list of the indices of the currently selected items in the 1istbox. 


—_——— ee eee 
Example 33 


Script Example 


## Create and display an empty listbox 

listbox .1 —height 3 

grid .1 

i## Add 3 elements to the listbox\\ 

i## Note — insert at end position — order is as expected 
.| insert end first 

.| insert end second 

.l insert end third 
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i## User selects second item 
puts "Selected: [.1 curselection]" 


Script Output 
Selected; 1 


Syntax: JistboxName get first ?last? 
Returns a list of the text displayed in the range of entries identified by the 
indices. 


first The first entry to return. 


last The last entry to return. If this is not included, only the first entry 
is returned. The range returned is inclusive. 


——— ee OOO 
Example 34 


Script Example 


if Create and display an empty listbox 
listbox .1 —height 3 

pack .1 
i## Add 3 elements to the listbox 

i## Note — insert at end position — order is as expected 
.l insert end first 

.l| insert end second 

.| insert end third 

i## User selects second item 

puts "Selected Text: [.1 get [.]1 curselection]]" 


i I 


Script Output 


Selected Text: second 


By default, selecting an element in a listbox will export that selection to the window manager’s 
clipboard. This allows the selection to be cut/pasted into other tasks and also limits the listbox to a 
single selection. In order to select multiple items from a listbox, you must both disable the export 
function and enable multiple selection mode as shown in the right hand listbox in the next example. In 
the next example some selections were made before the graphic and report were created. 
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a 
Example 35 
Script Example 

if Create the left listbox, defined to allow only a single 

i## selection 


listbox .1Single —selectmode single —exportselection no 
grid .1Single -row 1 —column 0 


.|1Single insert end "top" "middle" "bottom" 

i## Create the right listbox, defined to allow multiple items 
## to be selected. 

listbox .1Multi —selectmode multiple —exportselection no 


grid .1Multi —row 1 —co 
.-IMulti insert end "Mul 


umn 1 
tiTop" "MultiMiddle" "MultiEnd" 


i## Create a button 
button .report —tex 


to report what’s been selected 
t "Report" —command "report" 


grid .report —row 0 


i## And a procedure 
dt = and display the 
proc report {} { 


—column 0 —columnspan 2 


to loop through the listboxes, 
selected values. 


foreach widget [list .1Single .1Multi] { 
set selected [$widget curselection] 
foreach index $selected { 
set str [$widget get $index] 
puts "$widget has index $index selected — $str" 


} 
Script Output 


.lSingle has index 1 selected - 
-lMulti has index 0 selected - 
-lMulti_ has index 2 selected - 


Report 


MultiTop 
MultiMiddle 
MultiEnd 


middle 
MultiTop 
MultiEnd 
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11.9 SCROLLBAR 


Since the 11stbox does not allow variables or commands to be associated with its selections, it seems 
less useful than the button or menu widgets. The 1istbox becomes important when you need to 
display a large number of selection values and you connect the 1istbox with a scrollbar widget. 


11.9.1 The Basic scrollbar 


The scrollbar widget allows you to show a portion of a widget’s information by using a bar with 
arrows at each end and a slider in the middle. To change the information displayed, a user clicks the 
arrows or bar, or drags the slider. At this point, the scrollbar informs the associated widget of the 
change. The associated widget is responsible for displaying the appropriate portion of its data to reflect 
that change. 


Syntax: scrollbar scrollbarName ?options? 


Create a scrollbar widget. 


scrollbarName The name for this scrollbar. 
options This widget supports several options. 
-command "cmdName ?args?" This defines the command to invoke when 


the state of the scrollbar changes. Argu- 
ments that define the changed state will be 
appended to the arguments defined in this 
option. Most commonly, the cmdName argu- 
ment is the name of the widget this scrol1 - 
bar will interact with. 


-orient direction Defines the orientation for the scrollbar. The 
directionmay be horizontal orvertical. 
Defaults to vertical. 


-troughcolor color Defines the color for the trough below the slider. 
Defaults to the default background color of the 
frames. 


A scrollbar interacts with another widget by invoking the defined command whenever the state 
of the scrollbar changes. The widgets that support scrolling (]istbox, text, and canvas) have 
subcommands defined to allow them to be scrolled. The commands that control the behavior of the 
scrollable widget and the scrollbar are discussed in more detail later in this chapter. 

The options that must be used to make a widget scrollable are -xscrol]command and/or 
-yscrollcommand. These are the equivalent of the scrollbar’s - command option. 


Syntax: widgetName -xscrollcommand script 
Syntax: widgetName -yscrollcommand script 


Defines the script to be evaluated when the widget view shifts, so that the scrollbar may reflect the 
state of the scrollable widget. Information about the change will be appended to this script. In the next 
example, the command to create the scrollbar includes the following option. 


—command .box yview 
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This registers the script .box yview with the scrollbar. When the scrollbar changes state (someone 
moves the slider, clicks the bar, and so on), the scrollbar will append information about the change 
to that script and evaluate it. The listbox, canvas, and text widgets each support a yvi ew sub- 
command that understands the arguments the scrollbar will append. The command to create the listbox 
includes the following option. 


-yscrollcommand ".scroll set" 


This registers the script .scrol]l set with the listbox. When the listbox changes state (for exam- 
ple, when lines are added or deleted), this information will be appended to that script, and the script 
will then be evaluated. The scrollbar supports a set subcommand to be invoked by this script. 

The following example shows a scrollbar connected with a listbox. 

Note the -sticky ns option to the grid command which tells the grid layout manager that the 
ends of the widget should stick to top and bottom of the frame. Without this option, the scrollbar 
would consist of two arrows with a |-pixel-tall bar, to use the minimal space. 

The equivalent pack option is -f111 y, which informs the pack layout manager that this widget 
should expand to fill the available space and that it should expand in the Y direction. 


$$$ Ae 
Example 36 
Script Example 
i## Create the scrollbar and listbox. 
scrollbar .scroll —command ".box yview" 
listbox .box —height 4 —width 8 \ 
—yscrollcommand ".scroll set" 


dt Grid them onto the screen — note —sticky option 
grid .box .scroll —sticky ns 


#f Fill the listbox. 
.box insert end0 123456789 10 


Script Output 


11.9.2 scrollbar Details 

In normal use, the programmer can just set the -command option in the scrollbar and the 
-yscrollcommand or -xscrollcommand in the widget the scrollbar is controlling, and everything 
will work as expected. For some applications, though, you need to understand the details of how the 
scrollbar works. The following is the sequence of events that occurs when a scrollbar is clicked. 


===) 
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. The user clicks an arrow or bar, or drags a slider. 
. The scrollbar concatenates the registered script (.box yview) and information about the change 


(moveto .2) to create a new script to evaluate (.box yview moveto .2). 


. The scrollbar evaluates the new script. 
. The widget changes its displayed area to reflect the change. 
. The widget concatenates its registered script and information that describes how it changed to create 


anew script(.scroll set .2 .5). 


. The widget evaluates that script to reconfigure the scrollbar to match the widget. 


The information the scrollbar appends to the script will be in one of the formats outlined in the 


following table. 


Command Subset Description Action 

scroll ?-?1 unit Scroll the displayed widget by one of the Click an arrow. 
smallest units (a line for a listbox or text 
widget, or a single pixel for a canvas). 

scroll ?-?1 page Scroll the displayed widget by the displayed Click the bar. 
area. For example, if four lines of a listbox 
are displayed, the listbox would scroll by four 
lines. 

moveto fraction Set the top of the displayed area to start Drag the slider. 
at the requested percentage. For example, in 
a 100-line listbox, .box yview moveto .2 
would start the display with line 20. 


In the preceding example, when the scrollbar is manipulated, a command of the form 
.box yview scroll 1 unit 
or 


.box yview moveto .25 


would be created by the scrollbar widget and then evaluated. The scrollbar’s set command will 
modify the size and location of the scrollbar’s slider. 


Syntax: scrol]barName set first last 
Sets the size and location of the slider. 


first A fraction representing the beginning of the displayed data in the associated 
widget (e.g., 0.25) informs the scrollbar that the associated widget starts 
displaying data at that point (e.g., the 25% point). The scrollbar will place 
the starting edge of the slider one fourth of the way down the bar. 


end A fraction representing the end of the displayed data in the associated 
widget (e.g., 0.75) informs the scrollbar that the associated widget stops 
displaying data at that point (e.g., the 75% point). The scrollbar will place 
the ending edge of the slider three fourths of the way down the bar. 
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Example 37 
Script Example 

i## Create and grid a scrollbar with no —command option 

scrollbar .sb 

grid .sb —row 0 —column 0 —sticky ns 


## Create and grid a listbox (to fill space and expand the 
dF scrollbar) 

listbox .1b 

grid .1b —row 0 —column 1 


## The scrollbar slider will start at the 1/3 position, 
## = =and stop at the 9/10 position. 
28D. SOk. 23-29 


Script Output 


= 
A script can also query a scrollbar to learn the positions of the slider with the get subcommand. 


Syntax: scro]]barName get 


Returns the current state of the widget. This will be the result of the most recent set 
command. 


($$ AAAAMDMMAaA 


Example 38 
Script Example 


scrollbar .sb 
sb set .3 .8 
puts "Start and end fractions are: [.sb get]" 


Script Output 


Start and end fractions are: 0.3 0.8 
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11.9.3 Intercepting scrollbar Commands 


The next example shows how you can use this knowledge about how the scrollbar works to use a single 
scrollbar to control two 1istbox widgets. This example uses a previously unmentioned subcommand 
of the 1istbox widget. 


Syntax: ]istboxName size 
Returns the number of entries in a 1istbox. 


a 
Example 39 
Script Example 

i## Create two listboxes 

listbox .leftbox —height 5 —exportselection 0 

listbox .rightbox —height 5 —exportselection 0 


## And fill them. The right box has twice as many entries as 
it =the left. 
for {set i 0} {$i < 10} {incr i} { 
.leftbox insert end "Left Line $i" 
.rightbox insert end "Right Line $i" 
.rightbox insert end "Next Right $i" 
} 


i## Display the listboxes. 
grid .leftbox —column 0 —row 0 
grid .rightbox —column 2 —row 0 


i## Create the scrollbar, set the initial slider size, and 
Ht display 


scrollbar .scroll —command \ 
"moveLists .scroll .leftbox .rightbox" 


i## The right listbox is displaying 5 of 20 lines 
scroll set 0 [expr 5.0 / 20.0] 
grid .scroll —column 1 —row O —sticky ns 


{HAHAHA AAA AAA A AAA AAA AAA AAA 


i## proc moveLists {scrollbar listboxl listbox2 args} — 


if Controls two listboxes from a single scrollbar 

if Shifts the top displayed entry and slider such that both 
i listboxes start and end together. The list with the most 
if entries will scroll faster. 

i 


if Arguments 


if scrollbar The 
if listboxl The 
if listbox2 The 


dt args The 
dt 

if Results 

dt No valid 

if Resets di 
if Resets si 


proc moveLists 


4 Get the hei 
if both ar 
set height [ 


dt Get the cou 
set sizel [$ 
set size2 [$ 


if {$sizel > 
set size 
} else { 
set size ${ 
} 


df Get the cur 
set scrollPos 


set startFrac 


## Calculate t 
set topl [exp 
set top2 [exp 


# Parse the a 
set cmdlst [s 


switch [Llinde 
"scroll" { 

# Parse cou 
foreach {sc 


if Determine 
## clicked ( 
# or "scrol 
if {[string 

set incre 


name of the scrollbar 

name of one listbox 

name of the other listbox 

arguments appended by the scrollbar widget 


return. 
splayed positions of listboxes. 
ze and location of scrollbar slider. 


{scrollbar listboxl listbox2 args} { 


ght for the listboxes — assume 
e the same. 


listbox2 cget —height] 


nt of entries in each box. 
istboxl size] 

istbox2 size] 

$size2} { 

{sizel}.0 


size2}.0 


rent scrollbar location 
ition [$scrollbar get] 
t [Llindex $scrol]lPosition 0] 


he top displayed entry for each listbox 
r int($sizel « $startFract)] 
r int($size2 *« $startFract)] 


rguments added by the scrollbar widget 
plit $args] 


x $cmdist 0] { 


nt and unit from cmdlst 
count unit} $cmdlst {} 


whether the arrow or the bar was 
is the command "scroll 1 unit" 

1 1 page") 

first units $unit] >= 0} { 
ment Lexpr 1 * $count]; 
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} else { 
set increment [expr $height * $count]; 


} 


if Set 
set to 
set to 
if {$t 
if {$t 
} 
"moveto 
if Get 
set to 
if {$t 


{ 


the new fraction for the top of the list 
pFractl [expr ($topl + $increment)/$size] 
pFract2 [expr ($top2 + $increment)/$size] 
opFractl < 0} {set topFractl 0} 
opFract2 < 0} {set topFract2 0} 


the fraction of the list to display as top 
pFract Llindex $cmdlst 1] 
opFract < 0} {set topFract 0} 


i## Scale the display to the number of entries in 


if the 


listbox 


set topFractl [expr $topFract * ($sizel/$size)] 
set topFract2 [expr $topFract * ($size2/$size)] 


} 
} 


if Move the listboxes to their new location 


$listbox 


yview moveto $topFractl 


$listbox2 yview moveto $topFract2 


if Reposi 
set topF 
2 $t 
if {$top 

set to 


} 


tion the scrollbar s] 
ract Lexpr ($topFract 


pFract Lexpr (1.0 — (¢ 


opFractl : $topFract2] 
Fract > (1.0 — ($height—1)/$size)} { 


ider 


> $topFract2) \ 


height—1)/$size)] 


set bottomFract Lexpr $topFract + (($height-1)/$size)] 
ar set $topFract $bottomFract 


$scrollb 


\|Next Right 2 
Right Line 3 


I | Next Right 3 
Right Line 4 
p)Next Right 4 


Note the calls to yvi ew in the previous example. The yvi ew and xvi ew subcommands set the start 
location for the data in a 1istbox. The first argument (scrol1 or moveto ) is used to determine how 


to interpret the 


other arguments. 
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When a scrollbar anda 1istbox are connected in the usual manner, with a line resembling 
scrollbar .scroll -command ".box yview" 


the scrollbar widget will append arguments describing how to modify the data to the arguments 
supplied in the -command argument, and the new string will be evaluated. The arguments appended 
will start with either the word scrol1 or the word moveto. For example, if an arrow were clicked in 
scrollbar .scrol1, the command evaluated would be: 


.box yview scroll 1 unit 


The .box procedure would parse the first argument (yvi ew) and evaluate the yvi ew procedure. 
The yview code would parse the argument scroll 1 unit to determine how the listbox should be 
modified to reflect scrolling one unit down. 

In the previous example, the slider does not behave exactly as described for the default scrol1bar 
procedures. Because we are scrolling lists of two different sizes, the slider size is set to reflect the 
fraction of data displayed from the larger listbox. The position of the slider reflects the center of the 
displayed data, rather than the start point. By changing the parameters to $scrollbar set, you can 
modify that behavior. For instance, you could position the slider to reflect the condition of one 1 is tbox 
and treat the other listbox as a slave. 


11.10 THE scale WIDGET 


The scale widget allows a user to select a numeric value from within a given range. It creates a bar 
with a slider, similar to the scrollbar widget, but without arrows at the ends. When the user moves 
the slider, the scale widget can either evaluate a procedure with the new slider location as an argument 
or set a defined variable to the new value, or perform both actions. 


Syntax: scale scaleName ?options? 
Create a scale widget. 
scaleName The name for this scale widget. 
?options? 
There are many options for this widget. The minimal set is: 


-orient orientation Whether the scale should be drawn horizontally or verti- 
cally. orientationmay be horizontal orvertical. 
The default orientation is vertical. 


ength numPixels The size of this scale. The height for vertical widgets and 
the width for horizontal widgets. The height may be in 
any valid distance value (as described in Section 11.2.3). 
- from number One end of the range to display. This value will be dis- 
played on the left side (for horizontal scale widgets) or 
top (for vertical scale widgets). 


-to number The other end for the range. 


380 CHAPTER 11 Introduction to Tk Graphics 


-label text 


-command script 


-variable varName 


-resolution number 


The label to display with this scale. 

The command to evaluate when the state changes. The 
new value of the slider will be appended to this string, 
and the resulting string will be evaluated. 

A variable that will contain the current value of the slider. 


The resolution to use for the scale and slider. Defaults 
to l. 


-tickinterval number The resolution to use for the scale. This does not affect 


the values returned when the slider is moved. 


The next example shows two scale widgets being used to display temperatures in Celsius and 
Fahrenheit scales. You can move either slider and the other slider will change to display the equivalent 


temperature in the other scale. 


xo 


Example 40 
Script Example 


## Convert the Celsius temperature to Fahrenheit 
proc celsiusTofahren {ctemp} { 


global fahrenheit 


set fahrenheit Lexpr ($ctemp*1.8) + 32] 


} 


i## Convert the Fahrenheit temperature to Celsius 


proc fahrenToCelsius {ftem 
global celsius 
set celsius [expr ($ftem 


} 


if Create a scale for fahre 


set fahrenscale [scale .fht 


p} { 


heit 


from 0 —to 100 —length 250 


—resolution .1 —tickin 


verva 


—ori 


p—32)/1.8] 


temperatures 
ent horizontal \ 


\ 


Ro 


0 —label "Fahrenheit" \ 


—variable fahrenheit —command fahrenToCelsius ] 


i## Create a scale for celsius te 
set celscale [scale .cel —orient horizontal \ 


from —20 —to 40 —length 250 \ 


—resolution .1 —tickinterva 
—variable celsius —command celsiusTofahren] 


if Grid the widgets. 
grid $fahrenscale 
grid $celscale 


peratures. 


20 —label "Celsius" \ 
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Fahrenheit 


00 20.2 399 60.1 79.8 100.0 


Celsius 


11.11 NEW WINDOWS 
When the wish interpreter is initialized, it creates a top-level graphics window. This window will be 
drawn with whatever decorations your display system provides and will expand to fit whatever other 
widgets are placed within it. If you find you need another, separate window, one can be created with 
the toplevel command. 
Syntax: toplevel windowName ?options? 
Creates a new top-level window. 
windowName The name for the window to create. The name must start 
with a period and conform to the widget naming conven- 
tions described in Section 11.2.1. 
?options? Valid options for the toplevel widget include: 


-relief value Sets the relief for this window. The value may be 
raised, sunken, ridge, or flat. The default is flat. 

-borderwidth size Sets a border to be size wide if the -relief option is not 
flat. The size parameter can be any dimensional value, 
as described in Section 11.2.3. 

-background color The base color for this widget. The co] or may be any color 
value, as described in Section 11.2.2. 


-height The requested height of this window, in units as described 
in Section 11.2.3. 
-width The requested width of this window, in units as described 


in Section 11.2.3. 


ooo —_.”—n— Oy» z= 
Example 41 


Script Example 


if Create a label in the original window 
label .1 —text "I’m in the original window" 
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it Create a new window, and a label for it 
toplevel .otherTopLevel 
label .otherTopLevel.|] —text "I’m in the other window" 


it Display the labels. 
grid .] 
grid .otherTopLevel.1 


‘min the original window . 
Af 


By default, the window name is shown in the top window decoration. This can be modified with 
the wm title command. For example, this command: 


wm title. "My Application" 


will change the name in a main application window. The wm command gives the Tk programmer 
access to the services provided by the Window manager. These services vary slightly between window 
managers and operating systems. You should read the on-line documentation for the subcommands 
supported by the wm command. 


11.12 INTERACTING WITH THE EVENT LOOP 


The Tk event loop is processed whenever the interpreter is not evaluating a command or procedure. It 
is best to write your code to spend as little time as possible within procedures. However, some tasks just 
plain take a while, and you may need to schedule passes through the event loop while your procedure 
is running. 

A classic error in event-driven GUI programming is to place a command that modifies the display 
inside a loop but not to force the display to update. (For example, a loop that performs some lengthy 
calculation might update a completion bar.) If the event loop is not entered, only the final graphic 
command will be evaluated. The loop will run to completion without modifying the display, and then, 
suddenly, the display will show the completed image. You can force the Tcl interpreter to evaluate the 
event loop with the update command. 


Syntax: update ?idletasks? 
Process the event loop until all pending events have been processed. 


idletasks Do not process user events or errors. Process only pending internal 
requests, such as updating the display. 
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The next example shows a small loop to put characters into a label. Without the update in the loop, 
the task would pause for several seconds and then display the complete string. The update command 
causes the characters to be displayed one at a time. 


———————— eee eee 
Example 42 


Script Example 


i## Create the label. 
label .1 —text "" —width 25 
grid .1 
if Assign some text. 
set str "Tcl makes programming Fun" 
## And add new text to the label one character at a time. 
for {set i 1} {$i < [string length $str]} {incr i} { 
.| configure —text [string range $str 0 $i] 
update idle 
i## Mark time for a second or so. 
# (Better delay technique described in the next section) 
for {set j 0} {$j < 1000} {incr j} { 
set x Lexpr $j *« .02] 


} 
Script Output 


After 5 seconds After 12 seconds After 20 seconds 
Tcl makes Tcl makes progr Tcl makes programming Fun 


11.13 SCHEDULING THE FUTURE: after 


The previous example uses a busy loop to cause the script to pause between inserting characters into 
the label. This is a pretty silly waste of CPU time, and Tcl provides a better way to handle this. The 
after command will perform one of three tasks. 


e If invoked with a single numeric argument, it will pause for that many milliseconds. 

e If invoked with a numeric argument and a script, it will schedule that script to be run the requested 
number of milliseconds in the future and continue processing the current script. 

e If invoked with a subcommand, it provides support to examine and cancel items from the list of 
scheduled tasks. 


Syntax: after milliseconds ?script? 
Pause processing of the current script or schedule a script to be processed in the future. 
milliseconds The number of milliseconds to pause the current processing, or the 
number of seconds in the future to evaluate another script. 


script If this argument is defined, this script will be evaluated after mi 1 - 
l17seconds time has elapsed. The after command will return a 
unique key to identify this event. 
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Syntax: after subcommand option 
Manipulate the scheduled queue of timer events. 


subcommand If the second argument is a subcommand name, that subcommand is 
evaluated. Some of these are discussed in the next section. 


The next example shows the after command being used instead of the busy loop. Then it shows 
events being scheduled in the future to remove the characters from the label. 


a 


Example 43 
Script Example 


if Create the label. 
label .1 —text "" —width 40 
grid .1 


if Assign some text. 


set str "Tcl makes programming Fun" 


if And add new text to the label one character at a time. 
for {set i l} {$i < [string length $str]} {incr i} { 
.| configure —text [string range $str 0 $i] 


update 
after 1000 


} 


{HEAR AAA AAA AAA AAA AE 


## proc shortenText {widget} — 

if Remove the first character fro 
if widget 

if Arguments 

if widget The name of a widge 
dt 

if Results 

if Removes the first character fro 


i## provided widget if one exists. 


if Schedules itself to run again if 


if empty. 
proc shortenText {widget} { 


it Get the current text string from the widget 


set txt [$widget cget —text] 


i## If it’s empty, we’re done. 
if {$txt eq ""} { 
return; 


} 


t with a —tex 


the text st 


the —text s 


the displayed string of a 


t option 


ing of the 


tring wasn’t 


11.13 Scheduling the Future: after 385 


# shorten the string 
set txt [string range $txt 1 end] 


if Update the widget 
$widget configure —text $txt 


if And schedule this procedure to be run again in 1 second. 
after 1000 shortenText $widget 


} 


shortenText .1 


Script Output 
Filling 
After 9 seconds After 24 seconds 
Emptying 
Atter 4 second Atte econd 


The first loop (filling the widget) is the type of process that occurs immediately to programmers 
who are used to working in nonevent-driven paradigms. The style of programming demonstrated by 
the shortenText procedure’s use of the after command is less intuitive but more versatile. 

In the first style, the event loop is checked only once per second. If there were an ABORT button, 
there would be a noticeable lag between a button click and the task being aborted. Using the second 
style, the GUI will respond immediately. 

Note that the shortenText procedure is not recursive. It does not call itself, it calls the after 
command to schedule itself to be called again. 


11.13.1 Canceling the Future 


Sometimes, after you have carefully scheduled things, plans change and schedules need to change. 
When the after command is evaluated, it returns a handle for the event that was scheduled. This 
handle can be used to access this item in the list of scripts scheduled for future evaluation. 


Syntax: after cancel handle 
Cancel a script that was scheduled to be evaluated. 


handle The handle for this event that was returned by a previous 
after milliseconds script command. 


We will use the after cancel command in the next chapter. 
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Example 44 
i## Schedule the task to exit in 10 seconds 
set exitEvent Lafter 10000 exit] 
button .b -text "Click me to cancel exit!" \ 
-command "after cancel $exitEvent" 
pack .b 


If your script needs information about events in the after queue, you can query the queue with 
the after info command. 


Syntax: after info ?handle? 
Returns information about items in the after queue. 


?handle? If after info is invoked with no hand1/e, it will return a 
list of all the handles in the queue. If invoked with a handle 
argument, after info will return a list consisting of: 

1. The script associated with this item. 

2. The word idle or timer. The word ide indicates that 
this script will be evaluated when the idle loop is next run 
(no other script requires processing), whereas timer indi- 
cates that the event is waiting for the timer event when the 
requested number of milliseconds has elapsed. 


eee 
Example 45 


i## ... many events added to timer queue 
## Delete the exit event from the queue 
foreach id [after info] { 
if {[string first exit Lafter info \$id]] >= 0} { 
after cancel \$id 


} 


11.14 BOTTOM LINE 
This chapter has introduced most of the simple Tk widgets. The text widget, canvas widget, and 
megawidgets (file boxes, color selectors, and so on) are covered in the next three chapters. 


e The Tk primitive widgets provide the tools necessary to write GUI-oriented programs with support 
for buttons, entry widgets, graphics display widgets, scrolling list boxes, menus, and numeric input. 
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Widget names must start with a period followed by a lowercase letter. (See Section 11.2.1.) 

Colors can be declared by name, or red/green/blue intensity values. (See Section 11.2.2.) 
Dimensions and sizes can be declared as pixels, inches, millimeters, or points. (See Section 
11:2:3:) 

The default widget configuration options are adequate for most uses. Options can be set when 
the widget is created with -option value pairs, or modified after a widget is created with the 
widgetName configure command. 

Syntax: widgetName configure ?optl? ?vall?... ?optN? ?valN? 

The value of a widget’s option is returned by the widgetName cget command. 

Syntax: widgetName cget option 

A label will display a single line of text. 

Syntax: label JabelName ?optionl? ?option2?... 

A button widget will evaluate a script when it is clicked. 

Syntax: button buttonName ?optionl? ?option2?... 

The entry widget will allow the user to enter text. 

Syntax: entry entryName ?options? 

A frame widget can be used to hold other widgets. This makes it easier to design and maintain 
a GUI. 

Syntax: frame frameName ?options? 

Radio and check buttons let a user select from several options. 

Syntax: radiobutton radioName ?options? 

Syntax: checkbutton checkName ?options? 

A menu contains elements that can be activated or selected. The elements can be commands, radio 
buttons, check buttons, separators, or cascading menus. 

Syntax: menu menuName ?options? 

A menu can be attached to a menubutton, or to a window’s menubar. 

Syntax: menubutton buttonName ?options? 

$windowname configure -menu $menuName 

A listbox displays multiple text elements and allows a user to select one or more of these elements. 
Syntax: listbox listboxName ?options? 

A scrollbar can be connected toa listbox, text, or canvas widget. 

Syntax: scrollbar scrollbarName ?options? 

The scale widget lets a user select a numeric value from a range of values. 

Syntax: scale scaleName ?options? 

Tk widgets can be arranged on the display using the place, grid, or pack layout manager. 
New independent windows are created with the top] evel command. 

Syntax: toplevel windowName ?options? 

The update command can be used to force a pass through the event loop during long computations. 
The after command can be used to pause an application or to schedule a script for evaluation in 
the future. 

The after cancel command can be used to cancel a script that was scheduled to be evaluated in 
the future. 
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11.15 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under a 
minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e 100 Which of the following are valid window names? What is the error in the invalid names? 
.b 
.Button 
-button 
.b2 
.2b 
-buttonFrame.b1 
.top.buttons.b1-quit 
..button 
. .b.1-quit 
e 101 What conventions does Tcl use to define colors? 
e 102 What conventions does Tcl use to define screen distances? 
e 103 What option will set the color of the text in a button? 
e 104 What is the difference between the return value of 
$widget cget -foreground 
and 
$widget configure -foreground 
e 105 How many lines of text can be displayed in a label widget? 
e 106 Can a button’s - command option contain more than one Tcl command? 
e 107 Can you use place to display a widget in a frame in which you are also using the pack 
command? 
e 108 How many items ina set of radiobuttons can be selected simultaneously? 
e 109 What types of items can be added to a menu? 
e 110 What widgets include scrollbar support by default? 
e 111 What is the time unit for the after command? 
e 112 What command will check for pending events? 
e 200 Write a GUI widget with an entry widget, label, and button. When the button is clicked, convert 
the text in the entry widget to pig Latin and display it in the label. The pig Latin rules are: 
e Remove the first letter. 


ee hoo SS 
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e If the first letter is a vowel, append ¢ to the end of the word. 

e Append the first letter to the end of the word. 

e Append the letters ay to the end of the word. 

201 Create a button and command pair in which each time the button is clicked it will change its 
background color. The text will inform the user of what the next color will be. The color change 
can be done with a list of colors, or by using an associative array as a lookup table. 

202 Write a data entry GUI that will use separate entry widgets to read First Name, Last Name, and 
Login ID. When the user clicks the Accept button, the data will be merged into proper location in a 
listbox. Insert new entries alphabetically by last name. Attach a scrollbar to the listbox. 

203 Add a Save button to the previous exercise. The command associated with this button will 
open a file and use Tcl commands to insert data into the listbox. Add a Restore button with a 
command to clear the listbox and load the data using the source command. Information in the 
save file will resemble the following. 


.listbox insert end "Doe, John: john.doe" 
.listbox insert end "Flynt, Clif: clif" 


204 Write a busy-bar application that will use a label to add characters to the text ina 1 abel widget 
to indicate a procedure’s progress. 

205 Turn the example in Section 6.4 into a GUI application. Add an entry widget to set the starting 
directory, a button to start searching the directories, a label to show the directory currently being 
examined, and a scrolling listbox to display the results. The text in the listbox should have leading 
spaces to denote which files are within previous directories. You may need to create the listbox with 
-font {courier} to display the leading spaces. 

206 Write a GUI with two sliders and a label. The label will display the result of dividing the value 
in the first slider by the value in the second slider. 

207 Write a procedure that will create a pop-up window using the toplevel command with an 
information label, and an OK button that will destroy the pop-up when clicked. 

208 A top-level window can appear anywhere on the screen. Write a procedure named frame - 
toplevel that will accept as a single argument the name of a frame to create. The procedure 
should create the frame, place it in the center of the parent window, and return the name of the 
new frame. Change the top]evel command in the previous exercise to frame-toplevel. What 
is different between the two implementations? 

300 Modify the frame-toplevel procedure from the previous exercise to accept an undefined 
number of arguments (for example, -background yellow -relief raised -borderwidth 
3) and use those arguments to configure the new frame widget. 

301 A Pizza class was created in Problem 9.204. Make a GUI front end that will allow a user to 
select a single size or style, and multiple toppings with a Done button to create a new Pizza object. 
302 Add a button to the result of the previous exercise that will generate a description of all Pizza 
objects in a scrolled listbox within a new top-level window. 


CHAPTER 


Using the canvas Widget 


Chapter 11 described many of the Tk widgets that support GUI programming. This chapter discusses 
the canvas widget, Tcl events, interaction with the window manager, and use of the Tcl image object. 
You will learn how events can be connected to a widget or an item drawn on a canvas, and how to use 
a canvas to build your own GUI widgets. 

The canvas is the Tk widget drawing surface. You can draw lines, arrows, rectangles, ovals, text, 
or random polygons in various colors with various fill styles. You can also insert other Tk windows, or 
images in X-Bitmap, PPM (Portable Pixmap), PGM (Portable GrayMap), or GIF (Graphical Interface 
Format) format (other formats are supported in various Tk extensions, discussed in Chapter 17). If that 
is not enough, you will explore writing C code to add new drawing types to the canvas command. 

As mentioned in Chapter 11, Tk is event oriented. Whenever a cursor moves or a key is pressed, an 
event is generated by the windowing system. If the focus for your window manager is on a Tk window, 
that event is passed to the Tk interpreter, which can then trigger actions connected with graphic items 
in that window. 

The bind command links scripts to the events that occur on graphic items such as widgets, or 
items displayed in a canvas or text widget. Events include mouse motion, button clicks, key presses, 
and window manager events such as refresh, iconify, and resize. After an examination of the canvas 
and bind commands, you will see how to use them to create a specialized button widget, similar to 
those in Netscape, IE, and other packages. 


(2.1 OVERVIEW OF THE canvas WIDGET 


Your application may create one or more canvas widgets and map them to the display with any of 
the layout managers pack, grid, or place. The canvas owns all items drawn on it. These items are 
maintained in a display list and their position in that list determines which items will be drawn on top 
of others. The order in which items are displayed can be modified. 


12.1.1 Identifiers and Tags 

When an item is created on a canvas, a unique numeric identifier is returned for that item. The item can 
always be identified and manipulated by referencing that unique number. You can also attach a tag to 
an item. A tag is an alphanumeric string that can be used to group canvas items. A single tag can be 
attached to multiple items, and multiple tags can be attached to a single item. 


Tcl/Tk: A Developer’s Guide. DOI: 10.1016/B978-0-12-384717-1.00012-8 39 1 
© 2012 Elsevier, Inc. All rights reserved. 
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A set of items that share a tag can be identified as a group by that tag. For example, if you composed 
a blueprint of a house, you could tag all of the plumbing with p]umbing and then tag the hot water 
pipes with hot, the cold water pipes with cold, and the drains with drain. You could highlight all of 
the plumbing with a command such as the following. 


$blueprint itemconfigure plumbing -outline green 
You could highlight just the hot water lines with a command such as the following. 
$blueprint itemconfigure hot -outline red 


The following two tags are defined by default in a canvas widget. 
al] Identifies all of the drawable items in a canvas. 
current Identifies the topmost item selected by the cursor. 


12.1.2 Coordinates 


The canvas coordinate origin is the upper left-hand corner. Larger Y coordinates move down the 
screen, and larger X coordinates move to the right. The coordinates can be declared in pixels, inches, 
millimeters, centimeters, or points (1/72 of an inch), as described for dimensions in Section 11.2.3. 
The coordinates are stored internally using floating-point format, which allows a great deal of 
flexibility for scaling and positioning items. Note that even pixel locations can be fractional. 


12.1.3 Binding 

You can cause a particular script to be evaluated when an event associated with a displayed item 
occurs. For instance, when the cursor passes over a button, an <Enter> event is generated by the 
window manager. The default action for the enter event is to change the button color to denote the 
button as active. Some widgets, such as the button widget, allow you to set the action for a button 
click event during widget creation with the - command option. All widgets can have actions linked to 
events with the bind command, discussed in detail later in the chapter. 

The canvas widget takes the concept of binding further and allows you to bind an action to events 
that occur on each drawable item within the canvas display list. For instance, you can make lines 
change color when the cursor passes over them, or bind a procedure to a button click on an item. 

You can bind actions to displayed items either by tag (to cause an action to occur whenever an item 
tagged as plumbing is clicked, for instance) or by ID (to cause an action when a particular graphic 
item is accessed). For instance, you could bind a double mouse click event to bringing up a message 
box that would describe an item. A plumber could then double click on a joint and see a description of 
the style of fitting to use, where to purchase it, and an expected cost. 


12.2 CREATING A canvas WIDGET 


Creating a canvas is just as easy as creating other Tk widgets. You simply invoke the canvas command 
to create a canvas and then tell one of the layout managers where to display it. As with the other Tk 
commands, a command will be created with the same name as the canvas widget. You will use this 
command to interact with the canvas, creating items, modifying the configuration, and so on. 


12.2 Creating a canvas Widget 393 


Syntax: canvas canvasName ?options? 
Create a canvas widget. 
canvasName The name for this canvas. 


?options? 
Some of the options supported by the canvas widget are: 


-background color The color to use for the background of this 
image. The default color is light gray. 


-closeenough distance Defines how close a mouse cursor must be to 
a displayable item to be considered on that 
item. The default is 1.0 pixel. This value may 
be a fraction and must be positive. 


-scrollregion boundingBox Defines the size of a canvas widget. 
The bounding box is a list, left top 
right bottom, which defines the total 
area of this canvas, which may be larger 
than the displayed area. These coordi- 
nates define the area of a canvas widget that 
can be scrolled into view when the canvas 
is attached to a scrollbar widget. This 
defaults to 0 0 width height, the size of 
the displayed canvas widget. 


-height size The height of the displayed portion of the 
canvas. If -scrol1region is declared larger 
than this and scrollbars are attached to this 
canvas, this defines the height of the window 
into a larger canvas. The size parameter 
may be in pixels, inches, millimeters, and 


so on. 

-width size The width of this canvas widget. Again, this 
may define the size of a window into a larger 
canvas. 

-xscrollincrement size The amount to scroll when scrolling is 


requested. This can be used when the image 
you are displaying has a grid nature, and 
you always want to display an integral num- 
ber of grid sections and not display half-grid 
sections. By default, this is a single pixel. 


-yscrollincrement size The amount to scroll when scrolling is 
requested. This can be used when the image 
you are displaying has a grid nature, and 
you always want to display an integral num- 
ber of grid sections and not display half-grid 
sections. By default, this is a single pixel. 
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12.3 CREATING DISPLAYABLE canvas ITEMS 


As with other Tk widgets, when you create a canvas widget you also create a procedure with the same 
name as the widget. Your script can use this procedure to interact with the canvas to perform actions 
such as drawing objects, moving objects, reconfiguring height and width, and so on. 

The subcommand for drawing objects on a canvas is the create subcommand. This subcommand 
creates a graphic item in a described location. Various options allow you to specify the color, tags, and 
so on for this item. The create subcommand returns the unique number that can be used to identify 
this drawable item. 

The create subcommand includes a number of options that are specific to the class of item. Most 
drawable items support the following options, except when the option is not applicable to that class of 
drawable. For instance, line width is not applicable to a text item. 


-width width The width of line to use to draw the outline of this item. 


-outline color The color to draw the outline of this item. If this is an empty string, the 
outline will not be drawn. The default color is black. 


-fill color The color with which to fill the item if the item encloses an area. If this is 
an empty string (the default), the item will not be filled. 


-stipple bitmap The stipple pattern to use if the - fi 11 option is being used. 
-tag tagList A list of tags to associate with this item. 


The items that can be created with the create subcommand are examined in the sections that 
follow. 


9 
») 


12.3.1 The Line Item 
Syntax: canvasName create line xl yl x2 y2 ?xn yn? ?options? 


Create a polyline item. The x and y parameters define the ends of the line segments. 
Options for the 1 ine item include the following. 


-arrow end Specifies which end of a line should have an arrow 
drawn on it. The end argument may be one of 


first The first line coordinate 

last The end coordinate 

both Both ends 

none No arrow (default) 
-fill color The color to draw this line. 


-smooth boolean If set to true, this will cause the described line 
segments to be rendered with a set of Bezier splines. 

-splinesteps number The number of line segments to use for the Bezier 
splines if - smooth is defined true. 
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12.3.2 The Are Item 


Syntax: canvasName create arc xl yl x2 y2 ?options? 
Create an arc. The parameters x1 yl x2 y2 describe a rectangle that would enclose 
the oval of which this arc is a part. Options to define the arc include the following. 
-start angle The start location in degrees for this arc. The angle 
parameter is given in degrees. The 0-degree position is 
at 3:00 (the rightmost edge of the oval) and increases in 
the counterclockwise direction. The default is 0. 
-extent angle The number of degrees counterclockwise to extend the 
arc from the start position. The default is 90 degrees. 
-style styleType The style of arc to draw. This defines the area that will be 
filled by the - fi 11 option. May be one of: 
pieslice The ends of the arc are connected to the 
center of the oval by two line segments 
(default). 
chord The ends of the arc are connected to each 
other by a line segment. 


arc Draw only the arc itself. Ignore - fil] 
options. 
-fill color The color to fill the arc, if -style is not arc. 


12.3.3 The Rectangle Item 


Syntax: canvasName create rectangle xl yl x2 y2 ?options? 
Create a rectangle. The parameters x1 yl x2 y2 define opposite corners of the rect- 
angle. The rectangle supports the usual -fi11, -outline, -width, and-stipple 
options. 


12.3.4 The Oval Item 


Syntax: canvasName create oval xl yl x2 y2 ?options? 
Create an oval. The parameters x1 yl x2 y2 define opposite corners of the rectangle 
that would enclose this oval. The oval supports the usual -fill, -outline, 
-width, and -stipple options. 


12.3.5 The Polygon Item 
Syntax: canvasName create polygon xl yl x2 y2 ... xn yn ?options? 
Create a polygon. The x and y parameters define the vertexes of the polygon. A final 
line segment connecting xn, ynto x1, y1 will be added automatically. The polygon 
item supports the same - smooth and -splinesteps options as the line item, as well 
as the usual - fill, -outline, -width, and -stippl|e options. 
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12.3.6 The Text Item 


Syntax: canvasName create text x y ?options? 

Create a text item. The text item has the following unique options: 

-anchor position Describes where the text will be positioned relative to the 
x and y locations. 

The position argument may be one of: 

center Center the text on the position (default). 

n s e€ w ne One or more sides of the text to place on 

se Sw nw the position. If a single side is specified, 
that side will be centered on the x/y loca- 
tion. If two adjacent sides are specified, 
that corner will be placed on the x/y loca- 
tion. For example, if position is defined 
as w, the text will be drawn with the center 
of the left edge on the specified x/y loca- 
tion. If position is defined as se, the 
bottom rightmost corner of the text will 
be on the x/y location. 

-justify style If the text item is multi-line (has embedded newline 
characters), this option describes whether the lines should 
be right justified, left justified, or center justified. 
The default is left. 

-text text The text to display. 

-font fontDescriptor The font to use for this text. 


-fill color The color to use for this text item. 


12.3.7 The Bitmap Item 
Syntax: canvasName create bitmap x y ?options? 
Create a two-color bitmap image. Options for this item include: 
-anchor position _ This option behaves as described for the text item. 
-bitmap name Defines the bitmap to display. May be one of: 
@file.xbm Name of a file with bitmap data 
bitmapNameName of one of the predefined bitmaps 


The Tcl 8.6 distribution includes the following bitmaps for the PC, Mac, and UNIX platforms. 


error 
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The Mac platform supports the following additional bitmaps. 


Accessory application caution 


, A rN 


Hocument edition floppy 
=e 


pfolder preferences 


| 


stationery 


12.3.8 The Image Item 


Syntax: canvasName create image xl yl ?options? 

Create a displayed image item. An image can be created from a GIF, PPM, PGM, or 

X-Bitmap image. The image command is discussed later in the chapter. The cre- 

ate image command was introduced several revisions after the create bitmap 

command. The create image is similar to the create bitmap command but can 

be used with more image formats and is more easily extended. The create image 

command uses the same - anchor option as the create bitmap. The image to be 

displayed is described with the - image options, as follows. 

-image imageName The name of the image to display. This is the identifier handle 
returned by the image command. 


12.3.9 An Example 


The following example creates some simple graphic items to display a happy face. 


$$ 
Example 1 
Script Example 
i## Create the canvas and display it. 
canvas .c -height 140 -width 140 -background white 
pack .c 
if Create a nice big circle, colored gray 
.c create oval 7 7 133 133 -outline black -fill gray80 -width 2 


if And Two little circles for eyes 
.c create oval 39 49 53 63 -outline black -fill black 
.c create oval 102 63 88 49 -outline black -fill black 
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if A Starfleet insignia nose 
.c create polygon 70 67 74 81 69 77 67 81 -fill black 


it A big Happy Smile! 
.c create arc 21 21 119 119 -start 225 -extent 95 -style arc \ 
-outline black -width 3 


Script Output 


12.4 MORE canvas WIDGET SUBCOMMANDS 


The create subcommand is only one of the subcommands supported by a canvas widget. This 
section introduces some of them, with examples of how they can be used. 


2.4.1 Modifying an Item 


You can modify a displayed item after creating it with the i temconfigure command. This command 
behaves like the configure command for Tk widgets, except that it takes an extra argument to define 
the item. 


Syntax: canvasName itemconfigure tagOrId ?optl? ?vall? ?opt2 val2? 
Return or set configuration values. 
tagOrId_ Either the tag or the ID number of the item to configure. 
optl The first option to set /query. 


?vall? If present, the value to assign to the previous option. 


2 
Example 2 
Script Example 

i## Create a canvas with a white background 

set canv [canvas .c -height 50 -width 300 -background white] 


if Create some text colored the default black. 
set top [ $canv create text 150 20 \ 
-text "This text can be seen before clicking the button" ] 
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if Create some text colored white. 
if It won’t show against the background. 
set bottom [ $canv create text 150 30 -fill white \ 
-text "This text can be seen after clicking the button" ] 


if Create a button which will use itemconfigure to change the 
# colors of the two lines of text. 
set colorswap [button .bl -text "Swap colors" \ 
-command "$canv itemconfigure $top -fill white;\ 
$canv itemconfigure $bottom -fill black;"] 


grid $canv 
grid $colorswap 


Script Output 


his text can be seen before clicking the button 
This text can be seen after clicking the button 


Swap colors | Swap colors 


12.4.2 Changing the Display Coordinates of an Item 

The previous happy face example simply displayed some graphic items but did not save the identifiers. 
The next example creates the happy face and saves the item for one eye to use with the canvas widget 
subcommand coords. The coords subcommand lets you change the coordinates of a drawable item 
after the item has been displayed. You can use this to move an item or change an item’s shape. 


Syntax: canvasName coords tagOrId ?x1 yl? ... ?xn yn? 
Return or modify the coordinates of the item. 
tagOrId A tag or unique ID that identifies the item. 


?xl yl?... Optional x and y parameters. If these arguments are absent, the 
current coordinates are returned. If these are present, they will be 
assigned as the new coordinates for this item. 


xo 
Example 3 
Script Example 

JHA HAAR AAR AAA AAA AAA AAA AAA AAA AAA 

## proc wink {canv item }-- 

i## Close and re-open an ‘eye’ item. 

if Arguments 

if canv The canvas that includes this item. 

if =item An identifier for the ‘eye’ to wink 


400 CHAPTER 12 Using the canvas Widget 


dt 
if Results 


i## Converts Y coords for the specified item to center, then 


if restores them. 


i## The item is in its original state when this proc returns. 


proc wink {canv item} { 


iF 


it Get the coordinates for this item, and split them into 
# left, bottom, right and top variables. 


set bounding [$canv coords $item] 


set left Llindex $bounding 0] 
set bottom [lindex $bounding 1] 
set right [lindex $bounding 2] 


set top Llindex $bou 


ding 3] 


set halfeye Lexpr int($top-$bottom)/2] 


i## Loop to close the eye 
for {set i 1} {$i < $ha 


Lexpr $bottom + $i 
update 
after 100 
} 


feye} {incr i } { 
$canv coords $item $left Lexpr $top - $i] $right \ 


ie 


i## Loop to re-open the eye 


for {set i $halfeye} {$i 


update 
after 100 
} 


df Create the canvas and di 


>= 0} {incr i -1} { 
$canv coords $item $left [expr $top - $i] \ 
$right [expr $bottom + $i]; 


splay it. 


canvas .c -height 140 -width 140 -background white 


grid .c 


it Create a nice big circle, colored 
.c create oval 7 7 133 133 -outline 


if And Two little circles for eyes 
.c create oval 39 49 53 63 -outline 


set righteye [.c create ov 


al 102 63 


gray 
black -fill gray80 -width 2 


black -fill black 


88 49 -outline black \ 
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-fill black] 


if A Starfleet insignia nose 
.c create polygon 70 67 74 81 69 77 67 81 -fill black 


dt A big Happy Smile! 
-c create arc 21 21 119 119 -start 225 -extent 95 -style arc \ 
Script Output 


-outline black -width 3 
|__| 


Note that the coords subcommand, like most of the canvas widget subcommands, will accept 
either an ID or a tag to identify the item. The righteye item could also have been created with the 
following line. 


dt Now, wink at the folks 
wink .c $righteye 


.c create oval 102 63 88 49 -outline black \ 
-fill black -tag righteye 


The wink procedure would then be evaluated as follows. 
wink .c righteye 


Also notice the update command in the wink loops. If this were left out, the display would not 
update between changes. There would be a pause while the new images were calculated, but the display 
would never change. 


Moving an Item 


An item can be moved with the move subcommand, as well as with the coords subcommand. The 
move subcommand supports relative movement, whereas the coords command supports absolute 
positions. 


Syntax: canvasName move tagOrId xoffset yoffset 
Move an item a defined distance. 
tagOrId A tag or unique ID that identifies the item. 
xoffset yoffset The values to add to the item’s current coordinates to define the 
new location. Positive values will move the item to the right 
and lower on the canvas. 


402 CHAPTER 12 Using the canvas Widget 


For rectangle and oval items, the coordinates define the opposite corners and thus define the rectangle 
that would cover the item. In this case, it is easy to use the coords return to find the edges of the item. 

If you have a multi-pointed polygon such as a star, finding the edges is a bit more difficult. The 
canvas widget subcommand bbox returns the coordinates of the top left and bottom right corners of 
a box that would enclose the item. 


Syntax: canvasName bbox tagOrId 
Return the coordinates of a box sized to enclose a single item or multiple items with 
the same tag. 
tagOrId_ A tag or unique ID that identifies the item. If a tag is used and multiple 
items share that tag, the return is the bounding box that would cover all 
items with that tag. 


The next example creates a star and bounces it around within a rectangle. Whenever the bounding box 
around the star hits an edge of the rectangle, the speed of the star is decreased and the direction is 
reversed. 


— $$ 
Example 4 
Script Example 

i## Create the canvas and display it 

canvas .c -height 150 -width 150 

grid .c 


if Create an outline for the bouncing star’s boundary 
.c create rectangle 3 3 147 147 -width 3 -outline black \ 
-fi1l white 


i## Create a star item 
.c create polygon 11531005 5580105 16 5 12 10 \ 
14 15 8 12 -fill black -outline black -tag star 


i## Set the initial velocity of the star 
set xoff 2 
set yoff 3 


if Move the item forever 
while {1} { 
set box [.c bbox star] 
set left Llindex $box 0] 
set top [lindex $box 1] 
set right [lindex $box 2] 
set bottom [lindex $box 3] 


if If the star has reached the left margin, heading left, 
if or the right margin, heading right, make it bounce. 
jf Reduce the velocity to 90% in the bounce direction to 
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# account for elasticity losses, and reverse the X 
## component of the velocity 

if {(($xoff < 0) && ($left <= 3)) || 

(($xoff > 0) && ($right >= 147))} { 

set xoff [expr -.9 * $xoff] 


if The same for the Y component of the velocity. 
if {(($yoff < 0) && ($top <= 3)) || 

(($yoff > 0) && ($bottom >= 147))} { 
set yoff Lexpr -.9 * $yoff] 


.c move star $xoff $yoff 
update 


Script Output 


Pass 1 Pass 2 Pass 7 Pass 10 Pass 12 
a 


Tk stores the location of items in floating-point coordinates. Thus, the bouncing star does not com- 
pletely stop until the x and y velocities fall below the precision of the floating-point library on your 
computer. The star will just move more and more slowly until you get bored and abort the program. 
12.4.4 Finding Items, and Raising and Lowering Items 
The canvas can be searched for items that meet certain criteria, such as their position in the display list, 
their location on the canvas, or their tags. The canvas widget subcommand that searches a canvas is 
the find subcommand. It will return a list of unique IDs for the items that match its search criteria. The 
list is always returned in the order in which the items appear in the display list, the first item displayed 
(the bottom if there are overlapping items) first, and so on. 

The items in a canvas widget are stored in a display list. The items are rendered in the order 
in which they appear in the list. Thus, items that appear later in the list will cover items that appear 
earlier in the list. An item’s position in the display list can be changed with the raise and lower 
subcommands. 


Syntax: canvasName raise tagOrId ?abovetagOrId? 
Move the identified item to a later position in the display list, making it display above 
other items. 
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tagOrid A tag or unique ID that identifies the item. 


?abovetagOrId? The ID or tag of an item that this item should be above. By default, 
items are moved to the end position in the display list (top of the 
displayed items). With this option, an item can be moved to loca- 
tions other than the top. In fact, you can raise an item to just 
above the lowest item, effectively lowering the item. 


Syntax: canvasName lower tagOrId ?belowtagOrId? 

Move the identified item to an earlier position in the display list, making it display 

below other items. 

tagOrid A tag or unique ID that identifies the item. 

?belowtagOrId? The ID or tag of an item that this item should be directly below. 
By default, items are moved to the first position in the display 
list (bottom of the displayed items). With this option, an item can 
be moved to locations other than the bottom. You can | ower an 
item to just below the top item, effectively raising the item. 


Syntax: canvasName find searchSpec 
Find displayable items that match the search criteria and return that list. 


searchSpec 
The search criteria. May be one of: 
all Return all items in a canvas in the order in 
which they appear in the display list. 
withtag Tag Returns a list of all items with this tag. 
above tagOrlId Returns the single item just above the one 


defined by tagOrId. If a tag refers to mul- 
tiple items, the last (topmost) item is used as 
the reference. 


below tagOrId Returns the single item just below the one 
defined by tagOrId. If a tag refers to mul- 
tiple items, the first lowest) item is used as 
the reference. 


enclosed xl yl x2 y2 Returns the items totally enclosed by the rect- 
angle defined by x1, yl and x2, y2. The 
x and y coordinates define opposing corners 
of a rectangle. 

overlapping xl yl x2 y2 Returns the items that are partially enclosed 
by the rectangle defined by x1, yl and x2, 
y2. The x and y coordinates define opposing 
corners of a rectangle. 

closest x y ?halo? Returns the item closest to the X/Y location 

?start? described with the x and y parameters. 
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If more than one item overlies the X/Y location, the one that is later in the display list is returned. 
When using the closest search specifier, the halo parameter is a positive integer that is added to the 
actual bounding box of items to determine whether they cover the X/Y location. 

The start parameter can be used to step through a list of items that overlie the X/Y position. If 
this is present, the item returned will be the highest item that is before the item defined by the start 
parameter. If the display list contained the item IDs in the order 1 2 3 4 9 8 7 65, and all items 
overlapped position 100,50, the command 


$canvasName find -closest 100 50 0 


would return item 1, the lowest object in the display table. 
The command 


$canvasName find -closest 100 50 0 8 


would return item 9, the item immediately below 8. 

The next example shows some overlapping items and how their position in the display list changes 
the appearance of the display. This example redefines the default font for the text items. This is 
explained in the next section. 

Note that the upvar command is used with the array argument. In Tcl, arrays are always passed 
by reference, not by value. Thus, if you need to pass an array to a procedure, you will call the procedure 
with the name of the array and use upvar to reference the array values. 


eee ee eee 
Example 5 


Script Example 


## proc showDisplayList {canv array}-- 

## «Prints the Display List for a canvas. 

if Converts item ID’s to item names via an array. 

if Arguments 

## canv. Canvas to display from 

if array The name of an array with textual names for the 

if display items 

## Results 

i## «Prints output on the stdout. 

proc showDisplayList {canv array} { 

upvar $array id 
set order [$canv find all] 
puts “display list (numeric): $order" 
puts -nonewline "display list (text): 
foreach i $order { 

puts -nonewline "$id($i)" 


" 


} 
puts 


wo 


canvas .c -height 150 -width 170 
pack .c 
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i## create a light gray rectangle with dark text. 


set tclSquare \ 

[.c create rectangle 10 20 110 140 \ 
-fill gray70 -outline gray70 ] 
set tclText [.c create text 60 30 -text “Tcl\nIs\nTops" \ 

-fill black -anchor n -font [list arial 20 bold ] \ 
-justify center ] 


i## create a dark gray rectangle with white text. 
set tkSquare \ 
.c create rectangle 60 20 160 140 -fill gray30 \ 
-outline gray30 J 
set tkText [.c create text 110 30 -text "“Tk\nTops\nTcl" \ 
-fill white -anchor n -font [list arial 20 bold ] \ 

-justify center ] 


J 


## Initialize the array with the names of the display items 

## = =linked to the unique number returned from the 

i## ~=canvas create. 

foreach nm [list tclSquare tclText tkSquare tkText] { 
set id(Lsubst $$nm]) "$nm" 


if Update the display and canvas 
update; 


if Show the display list 
puts "\nAt beginning" 
showDisplayList .c id 


jf Pause to admire the view 
after 1000 


it Raise the tclSquare and tclText items to the end \ 
# = =©(top) of the display list 

.c raise $tclSquare 

.c raise $tclText 


if Update, display the new list, and pause again 
update; 

puts "\nAfter raising tclSquare and tclText" 
showDisplayList .c id 

after 1000 


if Raise the tkText to above the tclSquare (but below tclText) 
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.c lower $tkText $tclText 


4 Update and confir 


update; 


showDisplayList .c 


wn 


puts "Find reports 


puts "Find reports 


is above tclSquare" 


puts "\nAfter ’lowering’ tkText" 


id 


that $id(L.c find above $tclSquare]) \ 


that $id(L.c find below $tclSquare]) \ 


is below tclSquare" 
puts “and items: [.c find enclosed 0 0 120 150] are \ 


enclosed within 0,0 and 120,15" 


Script Output 


At beginning 


display list (numeric): 1 2 3 4 


display list (text) 


F tclSquaretclTexttkSquaretkText 


After raising tclSquare and tclText 
display list (numeric): 3 4 1 2 


display list (text) 


: tkSquaretkTexttclSquaretclText 


After ‘lowering’ tkText 
display list (numeric): 3 1 4 2 


display list (text) 


: tkSquaretclSquaretkTexttclText 


Find reports that tkText is above tclSquare 


Find reports that tkSquare is below tclSquare 
enclosed within 0,0 and 120,15 


and items: 1 2 are 


12.4.5 Fonts and Text Items 


Fonts can be just as complex a problem as some 6,000 years of human endeavor with written language 
can make them. They can also be quite simple. The following discusses the platform-independent, 
simple method of dealing with fonts. Other methods are described in the on-line documentation under 
font. The pre-8.0 releases of Tk name fonts using the X Window system naming convention as 


follows. 
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-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing- 
width-charset-encoding. 


If you need to work with a version of Tk earlier than 8.0, you are probably on a UNIX sys- 
tem and can determine a proper name of an available font with the X11 command x1sfonts or 
xfontsel. 

With the 8.0 release of Tcl and Tk, life became much simpler: a font is named with a list of 
attributes, such as family ?size? ?style? ?style? If the Tcl interpreter cannot find a font that 
will match the font you requested, it will find the closest match. It is guaranteed that a font will be 
found for any syntactically correct set of attributes. It’s not guaranteed that you’ll get the same font on 
different systems. For example, if you have a 19.5 point font defined for your system, but the end user 
does not, the display will be rendered with the closest available font, which might be 18 or 22 point. 

The attributes that define a font are: 

family The family name for a font. On all systems times, helvetica, and courier are 

defined. A list of the defined fonts can be obtained with the font families command. 


size The size for this font. If this is a positive value, it is the size in points (1/72 of an inch). 
The scaling for the monitor is defined when Tk is initialized. If this value is a negative 
number, it will be converted to positive and will define the size of the font in pixels. 
Defining a font by point size is preferred and should cause applications to look the same 
on different systems. 


style The style for this font. May be one or more of normal (or roman), bold, italic, 
underline, or overstrike. 


Information about fonts can be obtained with the font command. The following discuss only some 
of the more commonly used subcommands. 


Syntax: font families ?-displayof windowName? 
Returns a list of valid font families for this system. 
-displayof windowName If this option is present, it defines the window (frame, 
canvas, topwindow) to return this data for. By default, 


“eo 


this is the primary graphics window “. 


The font measure command is useful when you are trying to arrange text on a display in an 
aesthetic manner. 


Syntax: font measure font ?-displayof windowName? text 
The font measure command returns the number of horizontal pixels the string text 
will require if rendered in the defined font. 
font The name of the font, as described previously. 


-displayof windowName If this option is present, it defines the window (frame, 
canvas, topwindow) to return this data for. By default, 


“eo 


this is the primary graphics window “. 


text The text to measure. 


If Tk cannot obtain an exact match to the requested font on your system, it will find the best match. 
You can determine what font is actually being used with the font actual command. 
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Syntax: font actual font ?-displayof windowName? 
Return the actual font that will be used when font is requested. 
font The name of the requested font. 


-displayof windowName If this option is present, it defines the window (frame, 
Canvas, topwindow) to return this data for. By default, 


ed) 


this is the primary graphics window “. 


With Tk 8.1, Tcl and Tk support the Unicode character fonts. These are encoded by preceding 
the four-digit Unicode value with \u. You can obtain information on the Unicode character sets at 
http://Unicode.org. 

Unicode provides a standard method for handling letters other than the U.S. ASCII alphabet. The 
Unicode alphabet uses 16 bits to describe 65,536 letters. Each alphabet is assigned a range of num- 
bers to represent its characters. With Unicode, you can represent Japanese Katakana, Korean Hangul, 
French, Spanish, Russian, and most other major alphabets. 

The following example steps through the fonts available on a modern Linux system and displays 
some sample text in ASCII and Unicode. Note that if the Unicode fonts are not supported in a given 
font, the Unicode numbers are displayed instead. This example was run using Tcl/Tk version 8.6b2. 


A$ A A 
Example 6 
Script Example 
i## Create a canvas and link it to a scrollbar 
canvas .c -height 950 -width 800 -yscrollcommand {.ysb set} 
scrollbar .ysb -orient vertical -command {.c yview} 
grid .c .ysb -sticky ns 
set ypos 15 


if Get the list of available font families 
set families [font families] 


## Step through the available families 
foreach family $families { 


.c create text 4 $ypos -font Llist times 16 bold] \ 
-text "$family" -anchor nw 


.c create text 240 $ypos -font Llist $family 16] \ 
-text "test line -- UNICODE: \u30Ab \u042f \u3072" \ 
-anchor nw 


.c create text 4 [expr $ypos+25] -font [list roman 14] \ 
-text "[font actual [list $family 16]]" -anchor nw 
.c create line 4 [expr $ypos+45] 800 [expr $ypost45] 
incr ypos 50 
} 
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update 


it Configure the canvas’s scroll area to be the 
i## bounding box of all available items. 


.c configure -scrollregion [.c bbox all] 


Script Output 


nGraphic test line - UNICODE: 4) Au 
amily UnGraphic -size 16 -weight normal -slant roman -underline 0 -overstrike 0 
‘TL Fixed test line — UNICODE: 4 A wD 
amily {ETL Fixed} -size 16 -weight normal -slant roman -underline 0 -overstrike O 
nDotum test line- UNICODE: 4 Au 
‘amily UnDotum -size 16 -weight normal -slant roman -underline O -overstrike 0 
entury Schoolbook L test line -- UNICODE: 4 A O 

ily {Century Schoalbook L} -size 16 -weight normal -slant roman -underline 0 -ov) 

test line - UNICODE: 4 Au 

amily UnjamoSora -size 16 -weight normal -slant roman -underline O -overstrike 0 
nPilgia test Line -- UNICODE: + AU 
‘amily UnPilgia -size 16 -weight normal -slant roman -underline 0 -overstrike 0 


amily {Serto Jerusalem Outline} -size 16 -weight normal -slant roman -underline O -¢ 
strangelo Edessa test line UNICODE val A UO 


‘amily {Estrangelo Edessa} -size 16 -weight normal -slant roman -underline 0 -overst 
fest line -- UNICODE: 1 AU 


test line - UNICODE: 4 Av 

‘amily UnVada -size 16 -weight normal -slant roman -underline 0 -overstrike 0 
Droid Sans Mono test line -- UNICODE: ~” A Zt 

‘amily {Droid Sans Mono} -size 16 -weight normal -slant roman -underline O -overstri 
strangelo Quenneshrin test line -- UNICODE: 4 AD 
‘amily {Estrangelo Quenneshrin} -size 16 -weight normal -slant roman -underline O -/ 
uxi Sans test line -- UNICODE: 4 A 

‘amily {Luxi Sans} -size 16 -weight normal -slant roman -underline O -overstrike 0 
nPen test line - UNICODE: 4 Hu 

amily UnPen -size 16 -weight normal -slant roman -underline 0 -overstrike O 

dit test line - UNICODE: 4 AU 

‘amily Yudit -size 16 -weight normal -slant roman -underline O -overstrike 0 
nShinmun test line - UNICODE; 4 At 

‘amily UnShinmun -size 16 -weight normal -slant roman -underline 0 -overstrike 0 
berto Mardin test line -- UNICODE: WAU 

amily {Serto Mardin} -size 16 -weight normal -slant roman -underline O -overstrike C 
Deja Vu Sans Mono test line -- UNICODE: v7 A U 

amily {DejaVu Sans Mono} -size 16 -weight normal -slant roman -underline 0 -overs! | 


12.4.6 Using a Canvas Larger than the View 


The previous example more than filled the area of the canvas. The actual area that’s being filled isn’t 
known until run time when the script learns what fonts are available. The -scrol1region option lets 
you define how much of the canvas is to be controlled by a scrollbar. 

When you create a canvas, you can provide -width xsize and -height ysize arguments to 
define the size of the canvas to display on the screen. If you do not also use a -scrollregion 
argument, the canvas will be xsize by ysize in size, and the entire canvas will be visible. 
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The -scrollregion command will let you declare that the actual canvas is larger than its visible 
portion. For example, 


canvas .c -width 200 -height 150 -scrollregion {0 0 4500 2000} 


creates a window 200 pixels wide and 150 pixels high into a canvas that is actually 4500 x 2000 pixels. 

If you attach scrollbars to this canvas, you can scroll this 200 x 150 pixel window around the larger 
space. The -xscrollincrement and -yscrollincrement arguments will let you set how much of 
the canvas should scroll at a time. For instance, if you are displaying a lot of text in a canvas, you would 
want to set the - yscrollincrement to the height of a line. This will cause the canvas to display full 
lines of text, instead of displaying partial lines at the top and bottom of the canvas as you scroll through 
the text. 

The next example shows a checkerboard pattern, with each square labeled to show its position in 
the grid. Because the -xscrollincrement is set to the size of a square, the full width of each square 
is displayed. Because the - yscrollincrement is half the size of a square, half the height of a square 
can be displayed. 

Note that the -scrol]region can include negative coordinates as well as positive. You can draw 
any location in a canvas, but you will not be able to scroll to it unless you have set the -scrollregion 
to include the area you have drawn to. 

If you have a complex image to create, and you do not know what the size will be until it is drawn, 
you can draw the image to a canvas and then determine the bounding box for the image with the 
canvasName bbox command. 


set coords [$canvasName bbox all] 


eer 
Example 7 


Script Example 


if Create the canvas with a small viewing area 
if and a much larger scrolling area 


canvas .c -width 200 -height 150 -scrollregion \ 
{-100 -200 4500 2000} -yscrollcommand \ 
{.scrollY set} -xscrollcommand {.scrollX set} \ 
-xscrollincrement 50 -yscrollincrement 25 


if Attach scrollbars 
scrollbar .scrollY -orient vertical -command ".c yview" 
scrollbar .scrollX -orient horizontal -command ".c xview" 


if grid the widgets 

grid .c -row 0 -column 0 

grid .scrollY -row 0 -column 1 -sticky ns 
grid .scrollX -row 1 -column 0 -sticky ew 


df Fill the canvas with alternating black & white 
if boxes containing the box coordinates in a 
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if contrasting color 


for {set y -200} {$y < 2000} {incr y 50} { 
set bottom [expr $y + 50] 
for {set x -100} {$x < 4500} {incr x 50} { 
set right [expr $x+50] 
if {(($y + $x) % 100) == 50} { 
set textColor white 


set fillColor black 
} else { 

set textColor black 

set fillColor white 


.c create rectangle $x $y $right $bottom \ 
-f7i] fillColor -outline gray30 

.c create text Lexpr $x+25] [expr $y+25] \ 
-text x\n$y" -font \ 
[list helvetica 16 bold] -fill $textColor 


IU 650 Mra 750 
hi 650 Bt 650 


600 Be 700 Brel 
700 Braue 700 fra 


aD 150 
a 100 By es 100 ue 100 FF 


12.5 THE bind AND focus COMMANDS 


Section 12.1.3 mentioned that an event can be linked to a canvas item, and when that event occurs it 
can trigger an action. You can also bind actions to events on other widgets. This section discusses how 
this is done. 

Most of the Tcl widgets have some event bindings defined by default. For example, when you click 
ona button widget, the default action for the ButtonPress event is to evaluate the script defined in 
the - command option. 


12.5.1 The bind Command 


The bind command links an event to a widget and a script. If the event occurs while the focus is on 
that widget, the script associated with that event will be evaluated. 
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Syntax: bind widgetName eventType script 


Define an action to be executed when an event associated with this widget 
occurs. 


widgetName ‘The widget to have an action bound to it. 


eventType The event to trigger this action. Events can be defined in one of 
three formats: 


alphanumeric A single printable (alphanumeric 
or punctuation) character defines a 
KeyPress event for that character. 


<<virtualEvent>> A virtual event defined by your 
script with the event command. 


<modifier-type-detail> This format precisely defines any 
event that can occur. The fields of 
an event descriptor are described 
in the following. Where two 
names are together, they are syn- 
onyms for each other. For exam- 
ple, either Buttonl or Bl can 
be used to the left mouse button 
click. 


script The script to evaluate when this event occurs. 


The most versatile technique for defining events is to use the <modifier-type- 
detail> convention. With this convention, an event is defined as zero or more 
modifiers, followed by an event-type descriptor, followed by a detail field. 


modifier There may be one or more occurrences of the modifier field, 
which describes conditions that must exist when an event defined 
by the type field occurs. For example, Alt and Shift may be 
pressed at the same time as a letter KeyPress. Not all computers 
support all available modifiers. For instance, few computers have 
more than three buttons on the mouse, and most general-purpose 
computers do not support a Mod key. The modifiers Double, 
Triple, and Quadruple define rapid sequences of two, three, 
or four mouse clicks. Valid values for modifier are 


Button] Button2 Button3 Button4 Buttond 
Bl B2 B3 B4 B5 

odl Mod2 od3 Mod4 Mod5 

1 M2 3 M4 M5 

eta Alt Control Shift Lock 


Double Triple Quadruple 
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type This field describes the type of event. Only one type entry is 
allowed in an event descriptor. Valid values for type are: 
Activate Enter ap 
ButtonPress, Button Expose otion 
ButtonRelease FocusIn ouseWheel 
Circulate FocusOut Property 
Colormap Gravity Reparent 
Configure eyPress, Key Unmap 
Deactivate eyRelease Visibility 
Destroy Leave 

detail The detail provides the final piece of data to identify an event 


precisely. The value the detail field can take depends on the 
content of the type field. 


type 
ButtonPress 


ButtonRelease 


KeyPress 


KeyRelease 


Event Def inition Examples 


Event Definition 
<B1-Motion> 


a 
Shi ft_l 
<Shift_L> 


Description 


detail 


detai 1 will be the number of a mouse button 
(1 through 5). 


If the button number is specified, only events 
with that button will be bound to this action. 
If no detail is defined for a ButtonPress 
or ButtonRel ease event, any mouse-button 
event will be bound to this action. 


detail will specify a particular key, such as 
a or 3. 


Non-alphanumeric keys are defined by 
names such as Space or Caps_Lock. An 
X11 manual will list all of these. On a 
UNIX/Linux system you can run xkeycaps 
(www.jwz.org/xkeycaps/) to obtain a list of 
the available key types. If no detail is 
defined for a KeyPress or KeyRelease 
event, any keyboard event will be bound to 
this action. 


This event is generated if the left mouse button is pressed and the 
mouse moves; that is, when you drag an item on a screen. 


Generates an event when the A key is pressed. 


This does not define an event. Shi ft_L is not an alphanumeric. 


This event is generated when the left shift key is pressed. No event is 
generated when the key is released. 
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<KeyRelease-Shift_L> Generates an event when the left shift key is released. 

<Control-Alt-Delete> Generates an event if all three are pressed simultaneously. Not a 

recommended event for MSDOS-based hardware platforms. 

The bind command can pass information about the event that occurred to the script that is to be 
evaluated. This is done by including references to the events in the script argument to the bind 
command. The complete list of the information available about the event is defined in the bind on-line 
documentation. The information that can be passed to a script includes the following. 

%x The X component of the cursor’s location in the current window when the event occurs. 

*y The Y component of the cursor’s location in the current window when the event occurs. 

*%b The button that was pressed or released if the event is a ButtonPress or ButtonRelease. 

*k The key that was pressed or released if the event isa KeyPress or KeyRelease. 

*A The ASCII value of the key pressed or released if the event is a KeyPress or KeyRelease. 

*1 The type of event that occurred. 

*W The path name of the window in which the event occurred. 

bind .window <KeyPress> {keystroke 4k} 

Will invoke the procedure keystroke with the value of the key when a KeyPress event 

occurs and .window has focus. 

bind .win <Motion> {moveitem 2x sy} 

Will invoke the procedure moveitem with the x and y location of the cursor when a Motion 

event occurs and .win has focus. 


12.5.2 The canvas Widget bind Subcommand 


Events can be bound to a drawable item in a canvas, just as they are bound to widgets. The command 
to do this uses the same values for eventType and script as the bind command uses. 


Syntax: canvasName bind tagOrId eventType script 
Bind an action to an event and canvas object. 
tagOrId The tag assigned when an object is created, or the object identifier 
returned when an object is created. 
eventType The event to trigger on, as described previously. 


script A Tel script to evaluate when this event occurs. 


The following example is a network diagram showing the outside world, the firewall and four inter- 
nal routers. When a mouse enters any of the router boxes a popup label will appear displaying the 
parameters of that router. 


$$ $A 
Example 8 
Script Example 

JHA HAAR AAA AAA AAA AAA AAA AAA AA AA AAA AA AAA AAA AA AAA AAA 

i## proc showStatus {x y item}-- 

i## Report the status of an item in the global dictionary. 

## In a real-world system, the dictionary would be updated 

i at intervals. 
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dt 

if Arguments 

io xX Cursor X location 

ff oy Cursor Y location 

i## item Index into the dictionary 
i 

i## Results 

i## Temporary label is created. 

i 


proc showStatus {x y item} { 
global routerDict 


catch {destroy .statusLabel } 


set status "Name: $item\n" 

foreach {k v} [dict get $routerDict $item] { 
append status "$k: $v\n" 

} 


label .statusLabel -text $status -relief solid 
place .statusLabel -x $x -y $y 
} 


{HAHAHA ABA AAAAAA AAAAA AAAAAAAAAAAAAAE 


## proc drawItem {cvs itemDict item x y}-- 

if Recursive draw to step through ’feeds’ elements in dict 
if Arguments 

if =ocvs Canvas to draw on 

## = itemDict Dictionary of drawable items 
# = item The index of the item to draw 
# xX X location of center for item 
#ooY Y location of center for item 
i 

if Results 

i## =©=©Display is modified 

i 


proc drawltem {cvs itemDict item x y} { 


if First item in list is the outside world 
if Draw as oval. 
if All other items are internal routers. 
if Draw as rectangle. 


if {Llindex [dict keys $itemDict] 0] eq $item} { 
set type oval 

} else { 
set type rectangle 

} 
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cvs create $type [expr {$x - 40}] \ 
[expr {$y - 20}] Lexpr {$x + 40}] \ 
[expr {$y + 20}] -fill white -tag $item 


-tag $item 


if {![dict exists $itemDict $item feeds]} { 
return 


set feeds [dict get $itemDict $item feeds] 


cvs create text $x $y -text [string totitle $item] \ 
cvs bind $item <Enter> "showStatus %x ’y $item" 


# If this item doesn’t feed anything, return. 


set xPos [expr {$x - ((([Lllength $feeds]-1) * 100) / 2)}] 


set yPrev [expr {$y + 20}] 
set ylop [expr {$y + 50}] 
set yCenter [expr {$y + 70}] 


foreach feed $feeds { 


drawltem $cvs $itemDict $feed $xPos $yCenter 


$cvs create line $xPos $yTop $x $yPrev 
incr xPos 100 


} 


if Define a dictionary with an entry for each 
# on the network. 
dt 


i## Each entry is a dict of parameters (speed, 


foreach item {internet firewall} \ 
feeds {firewall {wireless 10-B-T Gig- 
status {up up} { 
dict lappend routerDict $item feeds $feeds 


} 


e 


S 


ement 
tatus, etc) 
thernet Fiber} } 


tatus $status 


foreach sub {wireless 10-B-T Gig-Ethernet Fiber} \ 
availability {public private private private} \ 
speed {1-Mbps 10-Mbps 1000-Mbps 10000-Mbps} \ 


status {down up up up} { 


dict lappend routerDict $sub availability $availability \ 


status $status speed $speed 


\ 
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set cvs [canvas .c -width 500 -height 250] 
grid $cvs 


drawltem $cvs $routerDict internet 250 30 


Firewall 


ee 


Wireless Gig-ethernet 


12.5.3 Focus 

When a window manager is directing events to a particular item (window, widget, or canvas item), that 
window is said to have the focus. Some events are always passed to an item that requests them, whether 
the item is defined as having focus or not. The cursor entering an item always generates an event, and 
a destroy event will always be transmitted to any applicable item. The keyboard events, however, are 
delivered only to the widget that currently has the focus. 

The window manager controls the top-level focus. The default behavior for Macintosh and MS 
Windows systems is to click a window to place the focus in a window. On UNIX/X Window systems, 
the window managers can be set to require a click or to place the focus automatically on the window 
where the cursor resides. 

Within the Tcl application, the focus is in the top-level window, unless a widget explicitly demands 
the focus. Some widgets have default actions that acquire the focus. An entry widget, for instance, 
takes the focus when you click it or tab to that widget. If you want to allow KeyPress events to be 
received in a widget that does not normally gain focus, you must add bindings to demand the focus. 

The next example shows a label widget .1 with three events bound to it: Enter, Leave, and 
KeyPress. When the cursor enters the .1 widget, it acquires the focus, and all KeyPress events will 
be delivered to the script defined in the bind .1 <KeyPress> command. When the cursor leaves 
label . 1, no events are passed to this item. 

The label .12 shares the same -textvariable as label .1. When | var is modified in response 
to an event on .1, it is reflected in .12. However, .12 never grabs the focus, as .1 does. The bind 
.12 <KeyPress> {append lvar "L2";} command has no effect, since . 12 never has focus. 


eee 
Example 9 


Script Example 


label .11 -width 40 -textvariable lvar -background gray80 
label .12 -width 40 -textvariable lvar 
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arid. idl 
grid .12 


bind .11 <KeyPress> {append lvar 2A; } 


bind .11 <Enter> { 
puts "Enter Event - grabbing focus 
focus .11 
} 


bind .11 <Leave> { 
puts "Leave Event - Returning focus" 
focus 
} 

bind .12 <KeyPress> {append lvar "L2";} 


puts "These events are valid on label .11: Cbind .11]" 


Label .11 has focus 


Label .11 has focus 


These events are valid on label .11: <Leave> <Enter> <Key> 
# I moved the cursor into label .11 

Enter Event — grabbing focus 

# I typed "Label .11 has focus" 

# I moved the cursor into label .12 

Leave Event — Returning focus 

# I typed "This has no effect" 


CREATING A WIDGET 


Now that we know how to create drawable items in a canvas and bind actions to events in that canvas, 
we can create our own widgets. For example, suppose we want an Opera/Firefox-style button that does 
one thing when you click it and another if you hold down the mouse button for more than one second. 

To create this we need to write a procedure that will create a canvas, draw something appropriate in 
that canvas, and bind scripts to the appropriate events. The following is a specification for a delayed- 
action button. 


e Will be invoked as delayButton name ?-option value? 
e¢ Required options will be: 
-bitmap bitmapName 
The bitmap to display in this button. 
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-commandl script 
A script to evaluate when button is clicked. 
-command2 script 
A script to evaluate when button is held down. 
¢ Optional arguments will include: 
-height number 
The height of the button. 
-width number 
The width of the button. 
-foreground color 
The foreground color for text and bitmap. 
-background color 
The background color for the button and bitmap. 
-highlight color 
The background color when the cursor enters the button. 
-text Text to display below bitmap 
The optional text to display below the bitmap. 
-font fontDescriptor 
The font for displayed text. 
e Clicking the widget with a left mouse button will invoke the command] script. 
¢ Holding down the left mouse button will invoke the command2 script. 
e The button will default to 48 x 48 pixels. 
e The button will default to a medium gray color. 
e The highlight color will default to light gray. 
e The button background will become the highlight color when a cursor enters the button. 
e The button background will return to normal color when the cursor leaves the button. 


This section shows a set of code that meets these specifications. The example shows the del ayBut - 
ton being used to display three simple buttons. There are a few things to notice in the next example. In 
the initialization, the configuration options are assigned default values before examining the argument 
list for modification. This lets the user override the defaults. Using the info locals to validate the 
options makes it easy to modify the code in the future. If a new configuration option becomes necessary 
(perhaps a - textColor instead of using the same color for the bitmap and text), you need only add a 
new default setting and change the code that uses the new value. The parsing code will not need to be 
modified. 

In contrast, parsing for required options needs to have a list of required options to check against. 
When the required options are changed, this list must also be modified. After the button is created 
event bindings can be assigned to it. These bindings cause the procedures in the del ayButton names- 
pace to be evaluated when the left mouse button is pressed or released. Note the way the after 
command is used to schedule the commands in scheduleCommand2, and to evaluate a command in 
invokeCommandl. 

When button | is pressed, the schedul eCommand2 procedure is evaluated. This procedure sched- 
ules the command2 script to be evaluated in one second, and saves the identifier returned by the after 
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command. It also appends a command that will delete the saved identifier when the command2 script 
is invoked. 

When the button is released, the invokeCommand1 procedure will check to see if there is still an 
event identifier for this window in the afters array. If there is, the <ButtonRelease> event came 
before the after event was evaluated. In this case, the command1 script will be evaluated, and the 
command2 event will be canceled. If there is no event identifier for this window in the afters array, 
it means the command2 script was already evaluated, and the procedure will return without evaluating 
the command] script. 

Also pay attention to the namespace commands. Because the after scripts are evaluated in global 
scope, full namespace identifiers are used for script names, and uplevel #0 is used to force scripts to 
evaluate in the global scope. 

Putting the registerCommands, scheduleCommand2, cancelCommand2, and invokeCom- 
mandl commands into a namespace protects these commands from possible collision with other 
commands and does not pollute the global space. Creating these procedures inside the namespace also 
allows them to create and share the associative arrays afters, commandlArray and command2Array 
without exposing these arrays to procedures executing outside this namespace. 

The sample script for the del ayButton does not include all the necessary procedures to use the 
menus or generate other data. It is only a skeleton to demonstrate the use of the delayButton. 


($a $$ $$ $a $$ 
Example 10 
Script Example 
HEHE HABA AAA AAA AAA AAA AA AAA AAA AAA AAA AAA AAA AAA AAA AAA 

# proc delayButton {delayButtonName args}-- 

if Create a delayButton icon that will evaluate a command when 

i## «clicked and display an information label if the cursor 

# rests on it 


if Arguments 
if delayButtonName The name of this delayButton 


if args A list of -flag value pairs 

# 

## Results 

if Creates a new delayButton and returns the name to the 
# calling script 


i## Throws an error if unrecognized arguments or required args 
if are missing. 


proc delayButton {delayButtonName args} { 
dHE Initialization 


## define defaults 
set height 48 

set width 48 

set background gray80 
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set highlight gray90 
set foreground black 
set text " " 

set commandl " 
set command2 " 
set bitmap " " 
set font {Helvetica 10} 


iHf Parse for Unsupported Options 
it Step through the arguments. 
i## Confirm that each -option is valid (has a default), 
i## and set a variable for each option that is defined. 
i## =3=oThe variable for -foo is "foo". 
foreach {option val} $args { 
set optName [string range $option 1 end] 
if {!Linfo exists $optName]} { 
error “Bad argument $option - \ 
must be one of Linfo locals]" \ 
"Invalid option" 


} 
set $optName $val 


} 


dHf =Parse for Required Options 
i## These arguments are required. 
set reqOptions [list -commandl -command2 -bitmap] 


it Check that the required arguments are present 
i## Throw an error if any are missing. 
foreach required $reqOptions { 
if {Llsearch -exact $args $required ] < 0} { 
error "delayButton requires a $required option" \ 
"Missing required option" 


} 


iHf «Button Creation 
if Create the canvas for this delayButton 
canvas $delayButtonName -height $height -width $width \ 
-background $background 


i## Place the bitmap in it. 
$delayButtonName create bitmap [expr $width/2] \ 

Lexpr $height/2] -bitmap $bitmap -foreground $foreground 
if If there is text, it goes on the bottom. 


if {![string match $text ""]} { 


$delayB 
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ttonName create text Lexpr $width/2] \ 


[expr $height-1] \ 
-text $text -fill $foreground \ 


-fo 
} 


HEE Bindi 
## =Bind 
# =oscrip 


bind $de 
"::de 


bind $de 
"::de 


the but 


ng Def 


t ing 


ayButt 
layBut 


ayButt 
layBut 


ini 
ton 
ob 


on 


CON: 


on 


Con: 


t $font -anchor s 


tion 

click to evaluate the $command 
al scope 

ame <ButtonPress-1> \ 


:scheduleCommand2 $delayButtonName" 


ame <ButtonRelease-1> \ 
:invokeCommand1 $delayButtonName" 


# Bind the background to change color when the 
# cursor enters 
bind $delayButtonName <Enter> \ 

"$delayButtonName configure -background $highlight" 


# Bind th 
i leaves, 
bind $del 
"$delayB 
::delayB 


iHE Comman 


if Register the co 


::delayB 
$co 


if And return the n 


return $d 
} 


it The regis 
if invokeCo 
if 1) avoid 
i## 2) make 
if «=60afterc 
## 3) make 
if 4) protec 
if = =from th 
i## 5) make 
# ~=opersist 


the 


the 


e background to change color when the cursor 
and cancel any pending display of an info label. 


ayButt 


ttonName 


tton:: 


on 


can 


ame <Leave> \ 
configure -background $background;\ 
celCommand2 $delayButtonName;" 


d Registration 


tton:: 
andl $ 


reg 
co 


ands 

isterCommands $delayButtonName \ 
and2 

ame 


elayButtonName 


terCo 
andl 
pollut 
"a 
ommand 
"a 
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ent 


an 
com 
ia 
fte 
pr 


fter 
"commandlArray" and "“command2Array" variables 
e rest of the program 

the “commandlArray" and “command2Array" variables 


ds, scheduleCommand2, cancelCommand2, and 
ands are defined within this namespace to 
the global space. 

rs" array of identifiers returned by the 
ivate to these procedures. 

s" array persistent 


namespace eval delayButton { 
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variable afters 

variable commandlArray 

variable command2Array 

MMMM MMe aaa Aaa 
## proc registerCommands {delayButtonName cmdl cmd2}-- 

if registers commands to be evaluated for this button 

if Arguments 

if delayButtonName The name of the delayButton 


if cmd Command to evaluate if clicked 
if cmd2 Command to evaluate if held 
if Results 


if New entries are created in the commandlArray 
i## and command2Array variables. 
proc registerCommands {delayButtonName cmd1l cmd2} { 
variable commandlArray 
variable command2Array 
set commandlArray($delayButtonName) $cmd1l 
set command2Array($delayButtonName) $cmd2 
} 


MMMM aaa aae Anal 
i## proc scheduleCommand2 {name }-- 
i## Cancel any existing "after" scripts for this button. 


if Arguments 
i## name The name of this delayButton 


if Results 
i## Places an item in the "after" queue to be evaluated 
i## 1 second from now 
proc scheduleCommand2 {delayButtonName } { 

variable afters 

variable command2Array 

cancelCommand2 $delayButtonName 

set cmd [format "%s; %s" $command2Array($delayButtonName) \ 

"[namespace current]::cancelCommand2 $delayButtonName" ] 

set afters($delayButtonName) [after 1000 $cmd] 

} 


MMMM Aa aaa eal 
i## proc cancelCommand2 {delayButtonName} - - 

dt Cancels the scheduled display of an Info label 

if Arguments 

if delayButtonName The name of the delayButton 

fl 

it Results 

i## If this label was scheduled to be displayed, 


12.6 Creating a Widget 425 


# it is disabled. 
proc cancelCommand2 {delayButtonName} { 
variable afters 
if {Linfo exists afters($delayButtonName) ]} { 
after cancel $afters($delayButtonName) ; 
} 
set afters($delayButtonName) "" 
} 


HMMM MMMM aaa 

df proc invokeCommandl {delayButtonName} - - 

i## Deletes the label associated with this button, and 

## resets the binding to the original actions. 

df Arguments 

## delayButtonName The name of the parent button 

if 

# Results 

i## No more label, and bindings as they were before the 

i## mouse paused 

# on this button 

proc invokeCommandl {delayButtonName} { 
variable afters 
variable commandlArray 


## If there is nothing in the ‘after’ identifier 

i## holder we’ve already done the ‘command 2’, 

df and this release is not part of a click. 

if {Lllength $afters($delayButtonName)] == 0} { 
return 

} 


dt Cancel the command 2 execution 
cancelCommand2 $delayButtonName 
i And do command 1 
uplevel #0 $commandlArray($delayButtonName) 
} 
} 


i## The following script shows how the delayButton} can be used 
HAHA BAAR AAA AAR AAA AAA AAA AA AAA AAA AAA AAR AAA AAA AAA AAA 
i## proc makeMenu {args}-- 

i## generate and post a demonstration menu 

if Arguments 

i## args A list of entries for the menu 

dF 

## Results 

i## Creates a menu of command items with no commands associated 
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## with them. 

proc makeMenu {args} { 
i## Destroy any previous .m window 
catch {destroy .m} 


if Create menu, add items 
menu .m 
foreach item $args { 

.m add command -label $item 
} 
.m post [winfo pointerx .] Lwinfo pointery .] 


} 


i## Create a button with text 

delayButton .bl -bitmap info -text "INFO" \ 
-commandl {tk_messageBox -type ok -message "Information"} \ 
-command2 {makeMenu "Tcl Info" "Tk Info" "Tcl00 Info" "Expect Info"} 


i## Create a button without text 
delayButton .b2 -bitmap hourglass \ 
-commandl {tk_messageBox -type ok \ 
-message [clock format [clock seconds]]} \ 
-command2 {makeMenu "Time in London" \ 
"Time in New York" "Time in Chicago"} 


if Create a button with non-default colors. 
delayButton .b3 -bitmap warning \ 
-command] {reportLatestAlert} \ 
-command2 {reportAllAlerts} \ 
-background #000000 -foreground #FFFFFF \ 
-highlight #888888 


grid .b1 .b2 .b3 


Script Output 


Initial button state 


@ © © delayButton.tcl 
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information 


A HELP BALLOON: INTERACTING WITH THE WINDOW MANAGER 


It also would be useful to be able to attach pop-up help balloons to widgets. Tk does not include a 
pop-up help widget as one of the basic widgets, but one can be created with just a few lines of code. 
The help balloon in this example is derived from an example on the Tcler’s Wiki site (http:-//wiki. tcl. tk). 
The behavior of the help balloon is as follows. 


e Schedule a help message to appear after a cursor has entered a widget. 
e Destroy a help message when the cursor leaves a widget. 
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Scheduling the window to appear, and destroying it when it is no longer required, can be done with 
the bind command, described previously. These bindings are established in the bal 1o0on procedure. 
When the cursor enters a widget, an after event is scheduled to display the help message, and the 
balloon is destroyed when the cursor leaves the requested window. 

The %W argument to the bind command is replaced by the name of the window that generated the 
event. This lets the script connect the help balloon to the window that created it. Displaying a balloon 
requires the following steps. 


Confirm that the cursor is still inside the window associated with this help balloon. 
Destroy any previous balloon associated with this window. 

Create a new window with the appropriate text. 

Map this window to the screen in the appropriate place. 


2 ON 


This is done in the bal ]oon::show procedure. Confirming that the cursor is still inside the win- 
dow associated with this help balloon and placing the help balloon in the correct location of the screen 
requires interacting with both the window manager and the Tk interpreter. The window manager con- 
trols how top-level windows are placed, whereas the Tk interpreter controls how widgets are placed 
within the application. 

The Tk wm and winfo commands provide support for interacting with window features such as 
window size, location, decorations, and type. The wm command interacts with the window manager, 
whereas the winfo command interacts with windows owned by the wish interpreter. 

On a Macintosh or Microsoft Windows platform, the window manager is merged into the operating 
system. On an X Window platform, the window manager is a separate program ranging from the simple 
wm and twm managers to the configurable modern window managers, such as Gnome/Enlightenment 
and CDE/KDE. There is a core of features supported by all window managers, and there are some 
subcommands supported only on certain platforms. Again, check the on-line documentation for your 
platform. 

The wm command is used to interact with top-level windows, the root screen and system-oriented 
features such as the focus model. The syntax of the wm command is similar to other Tk commands, 
with the command name (wm) followed by a subcommand and a set of arguments specific to this 
subcommand. 


Syntax: wm subcommand args 
Here are a few of the commonly used wm subcommands. 
The wm title command lets your script define the text in the top decoration. 
Syntax: wm title windowName text 
Assigns text as the title displayed in the window manager decoration. 
windowName The window to set the title in. 


text The new title. 


——— ee OO 
Example 11 


wm title . "Custom Title" 
grid [label .1 -text "Title Demonstration" ] 
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@® © © Custom Title 


|Title Demonstration 


The wm geometry command lets you control where windows are placed, and how large they are. 
Note that all wm commands are “suggestions” to the window manager. If your program requests unsup- 
ported behavior (like a 1280 x 1024 window on a 640 x 480 screen), the window manager may reject 
the request. 


Syntax: wm geometry windowName ?geometryString? 
Queries or modifies the window’s location or size. 
windowName The window to be queried or set. 


?geometryString? If this is defined, it instructs the window manager to change 
the size or location of the window. If not defined, the geome- 
try of the window is returned. 

The format of the returned geometry string will be: 
width x height+ xLocation+ yLocation 


A geometry string defined by a user can include just the 
dimension information (i.e., 500 x 200), or the location 
information (i.e., + 50+ 200). The usual technique for defin- 
ing location is with plus (+) markers, which denote pixels 
to the right and down from the top left corner. You can also 
describe the location with minus (—) markers, in which case 
the location is measured in pixels left or up from the bottom 
right corner. 


——— rhe 
Example 12 


i## This example moves the primary window slightly 


if Retrieve the geometry 
set g Lwm geometry .] 


# Parse it into width, height, x and y components 
lassign [split $g {+-x}] width height xloc yloc 


if Move the window down and right 

incr xloc 5 

incr yloc 5 

set newGeometry [format "+%st+%s" $xloc $yloc] 
wm geometry . $newGeometry 


430 CHAPTER 12 Using the canvas Widget 


The overrideredirect subcommand will turn off the decorative borders that let you resize and 
move windows. By default, top-level widgets are created with full decorations, as provided by the 
window manager. 


Syntax: wm overrideredirect windowName boolean 
Sets the override-redirect flag in the requested window. If true, the window is not 
given a decorative frame and cannot be moved by the user. By default, the override- 
redirect flag is false. 
windowName ‘The name of the window for which the override-redirect flag is 
to be set. 


boolean A Boolean value to assign to the override-redirect flag. 


The wm overrideredirect command should be given before the window manager transfers 
focus of a window. Unlike most Tcl/Tk commands, you may not be able to test this subcommand by 
typing commands in an interactive session. The difference between override-redirect true and 
false looks as follows. 


eee 
Example 13 


it Create a toplevel window with no decorations 
toplevel .tl -border 5 -relief raised 

label .tl.1 -text "Reset Redirect True" 

grid .t1.1 

wm overrideredirect .t1 1 


i## Create a toplevel window with normal decorations 
toplevel .t2 -border 5 -relief raised 

label .t2.1 -text "Default Redirect" 

grid .t2.1 


if Place the windows and raise them to the top of 
## the display list. 

wm geometry .tl +300+300 

wm geometry .t2 +300+400 

raise .tl 

raise . 


Reset Redirect True 
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The protocol command allows a script to examine or modify how certain windowing system 
events are handled. 


Syntax: wm protocol window ?protocolName? ?script? 
Return information about protocol handlers attached to a window, or assign a protocol 
handler to a window. 
window The name of a top-level Tk window (the main window or one 
created with the top|evel command). 


?protocolName ‘The name of an atom corresponding to a window manager proto- 
col. The only protocol in common use is WM_DELETE_WINDOW, the 
notification that a window has received a delete signal. 


If this field is absent, report all protocols that have handlers 
associated with them. 


?script? A script to evaluate when the protocol Name message is received. 


If this field is absent, return the script associated with the proto- 
colName atom. 


The common use for the wm protocol command is to catch the WM_DELETE_WINDOW request, and 
give the user an option to save work before exiting (or abort the exit completely). 

This is similar to using the bind command to catch the notification that a window has 
been destroyed: bind . <Destroy> {cleanExit }. The difference is that the wm protocol 
WM_DELETE_WINDOW command catches the request to delete a window, and can abort destroying the 
window, whereas the bind . <Destroy> command catches the notification that the window has 
already been destroyed. 


$$ Aa 
Example 14 
Script Example 
## Confirm that a user wishes to exit the application. 
proc confirmClose {} { 
set answer [tk\_messageBox -type "“yesno" \ 
-message "Do you wish to exit" ] 


if {{[string match $answer "yes"]} { 
## Might add call to a ‘save’ procedure here 
exit 

} else { 

return 

} 


wm protocol . WM_DELETE_WINDOW confirmClose 
puts "ALL Protocols with handlers: [wm protocol .]" 


puts “Handler for WM_DELETE_WINDOW: \ 
[wm protocol . WM_DELETE_WINDOW]" 
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Script Output 
ALL Protocols with handlers: WM DELETE WINDOW 
Handler for WM_DELETE_WINDOW: confirmClose 


The wm command gives the Tcl programmer access to information controlled by the window man- 
ager. The winfo command gives the Tcl programmer access to information controlled by the Tk 
application. This includes information such as what windows are children of another window, what 
type of widget a window is, the size and location of a widget, the location of the cursor, and so on. 

The pointerxy subcommand will return the coordinates of the cursor. 


Syntax: winfo pointerxy window 
Return the x and y location of the mouse cursor. These values are returned in screen 
coordinates, not application window coordinates. 
window The mouse cursor must be on the same screen as this window. If the cursor 
is not on this screen, each coordinate will be —1. 


7———_M_a_ 
Example 15 
i## Report the cursor location 
label .1 -textvar location 
grid .1 
while {1} { 
set location [winfo pointerxy .] 
update 
after 10 


The containing subcommand will return the name of a window that encloses a pair of 
coordinates. 


Syntax: winfo containing rootX rooty 
Returns the name of the window that encloses the X and Y coordinates. 
rootX AnX screen coordinate. (0 is the left edge of the screen.) 


rootY AY screen coordinate. (0 is the top edge of the screen.) 


————eehononrnhne 
Example 16 


i## This label displays ‘outside’ when the cursor is outside 

if the label, and ‘inside’ when the cursor enters the window. 
label .1 -textvar where 

grid .1 


while {1} { 
## Get the location of the cursor 
set location [winfo pointerxy .] 
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set in Leval winfo containing $location] 


## Is the cursor inside .1? 
if {{string match $in .1]} { 
set where inside 
} else { 
set where outside 


} 
update 
after 10 


The winfo height, winfo width, winfo rootx, and winfo rooty return the same infor- 
mation as the wm geometry command. However, whereas the wm geometry command can only be 
used for top-level windows, the winfo commands can also be used for individual widgets. 


Syntax: winfo height winName 
Syntax: winfo width winName 


Return height or width of a window. 
inName The name of the window. 


Ee 
Example 17 
puts "Toplevel window is [winfo width .] x Lwinfo height .]" 


Syntax: winfo rootx winName 


Syntax: winfo rooty winName 
Return x or y location of a window in screen coordinates. 
winName The name of the window. 


ox 


Example 18 
label .1 
pack .1 


puts "Label is at X: Lwinfo rootx .1] Y: [winfo rooty .1]" 
= 


The wm and winfo commands are used in the bal 1oon::show procedure to confirm that a help 
balloon is still required, and map it to the correct location if it is. The first step, confirming that the cur- 
sor 1s still within the window, can be done with two winfo commands. The pointerxy subcommand 
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will return the coordinates of the cursor, and the containing subcommand will return the name of a 
window that encloses a pair of coordinates. 

A help balloon window should not have the decorations added by the window manager, as we do 
not want the user to be able to move this window, iconify it, and so on. The decorations are added by 
the window manager, not managed by Tk, so removing the decorations is done with the wm command. 
The subcommand that handles this is overrideredirect. 

This example uses the message widget. A label only displays text exactly as it is formatted, 
whereas a message widget displays multi-line text and will add newlines to maintain a height/width 
ratio. The message is lighter weight than the text widget, discussed in the next chapter. 


Syntax: message name ?options? 
Create a message widget. 


name A name for the message widget. Must be a proper window name. 
?options? Options for the message include: 
-text The text to display in this widget. 
-textvar The variable which will contain the text to display in 
this widget. 
-aspect An integer to define the aspect ratio: (Xsize/Ysize) * 
100 


-background The background color for this widget. 


The final step is to place the new window just under the widget that requested the help balloon. The 
window that requests the help will be a window managed by Tk, so we can use the winfo command 
to determine its height and X/Y locations. Placing a top-level window on the screen is a task for the 
window manager, so the wm geometry command gets used. 


aw 
Example 19 
Script Example 
JHAAAR BAAR AAA AAA AR AAA AAA AAA AAA AAA AAA AAA AAP 
i## proc balloon {w help}-- 
i## Register help text with a widget 
if Arguments 


if ow The name of a widget to have a help balloon associated it 
# help The text to associate with this window. 
it Results 


i## Creates bindings for cursor Enter and Leave to display and 
i## destroy a help balloon. 


proc balloon {w help} { 
bind $w <Any-Enter> "after 1000 [list balloon::show “W Llist $help]]" 
bind $w <Any-Leave> "destroy %W.balloon" 

} 


namespace eval balloon { 
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HMM Meena 
it proc show {w text }-- 
## = =©3©Display a help balloon if the cursor is within window w 


it 

if Arguments 

it ow The name of the window for the help 
i## text The text to display in the window 
tf 

## Results 


if Destroys any existing window, and creates a new 
if toplevel window containing a message widget with 
i## =©6tthe help text 
proc show {w text} { 
dt Get the name of the window containing the cursor. 
set currentWin [eval winfo containing [winfo pointerxy .]] 


## If the current window is not the one that requested the 
# help, return, 
if {!£€string match $currentWin $w]} { 

return 


## The new toplevel window will be a child of the 
it window that requested help. 
set top $w.balloon 


## Destroy any previous help balloon 
catch {destroy $top} 


## Create a new toplevel window, and turn off decorations 
toplevel $top -borderwidth 1 
wm overrideredirect $top 


# If Macintosh, do a little magic. 
if {$::tcl_platform(platform) == "macintosh"} { 
if Daniel A. Steffen added an ‘unsupportedl’ command 
if to make this work on macs as well, otherwise raising the 
if balloon window would immediately post a Leave event 
## leading to the destruction of the balloon... The 
## ‘unsupportedl’ command makes the balloon window into a 
i floating window which does not put the underlying 
i## window into the background and thus avoids the problem. 
it (For this to work, appearance manager needs to be present.) 


# In Tk 8.4, this command is renamed to: 
if ::tk::unsupported: :MacWindowStyle 
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unsupp 
} 


i Create 
set hint 

-bac 
pack $hi 


## Get th 
i#f use t 
set wmx 
set wmy 


wm geome 
L[winfo 


if Raise 


ortedl style $top floating sideTitlebar 


and pack the message object with the help text 
[message $top.txt -aspect 200 \ 
kground lightyellow -font fixed -text $text] 
nt 


e location of the window requesting help, 

at to calculate the location for the new window. 
[winfo rootx $w] 

[expr [winfo rooty $w]+Lwinfo height $w]] 


try $top \ 
reqwidth $hint]xLwinfo reqheight $hint]+$wmx+$wmy 


the window, to be certain it’s not hidden below 


if other windows!. 
raise $top 


} 
} 


## Create a test button with a popup hint 


button .b 
balloon .b 
grid .b 


Push m 


-text Exit -command exit 
"Push me if you’re done with this 


e if 
you're done with 
this 


12.8 THE i 


mage OBJECT 


Creating items such as lines and arcs on a canvas is one way of generating a picture, but for some appli- 
cations a rasterized image is more useful. There are two ways of creating images in Tcl. The create 
bitmap canvas command will display a single color image on a canvas (as shown in Section 12.3.7). 
The create image canvas command will display an image object on the canvas. 
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The canvas bitmap item is easy to use but is not as versatile as the image object. You can use the 
image object to create simple bitmap images or full-color images. The full-color image objects can be 
shrunk, zoomed, subsampled, and moved from image object to image object. The image objects can 
be displayed in other widgets, including button, label, and text widgets. 

The standard Tk distribution supports images defined in the X-Bitmap, GIF, Portable Pixmap, and 
Portable GrayMap formats. Some extensions exist that provide support for other formats, such as JPEG 
and PNG. (See Chapter 14 for Jan Nijtmans’s Img Extension which adds more image support to Tk.) 
This section will explain how to create and use image objects. 


12.8.1 The image Command 

To create an image item on a canvas, you must first create an image object. The image command 
supports creating, deleting, and getting information about the image objects within the Tk interpreter. 
The image create command creates an image object from a file or internal data and returns a handle 
for accessing that object. 


Syntax: image create type ?name? ?options? 
Create an image object of the desired type, and return a handle for referencing this 


object. 

type The type of image that will be created. Tk versions 8.0 and more recent 
support: 
photo A multicolor graphic. 
bitmap A two-color graphic. 

?name? The name for this image. If this is left out, the system will assign a name 


of the form imageX, where X is a unique numeric value. 


?options? These are options specific to the type of image being created. The 
appropriate options are discussed in regard to bitmap and photo. 


An image can be deleted with the image delete command. 


Syntax: image delete name ?name? 
Delete the named image. 
name The handle returned by the image create command. 
The image command can be used to get information about a single image, or all images that exist in 
the interpreter. 
Syntax: image height name 
Return the height of the named image. 


Syntax: image width name 
Return the width of the named image. 


Syntax: image type name 
Return the type of the named image. 


For each of these commands, the name parameter is the image name returned by the image create 
command. You can retrieve a list of existing image names with the image names command. 
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Syntax: image names 
Return a list of the image object names. 


As with the Tk widgets, when an image is created with the image create command, a com- 
mand with the same name as the image is also created. This image object command can be used 
to manipulate the object via the imageName cget and imageName configure commands. These 
commands behave in the same way as other widget cget and configure subcommands. The config- 
uration options that can be modified with the configure subcommand depend on the type of image 
created and are the same as the options available to that image create type command. 


12.8.2 Bitmap Images 

Bitmap images (which are different from a canvas bitmap item) are created with the command image 

create bitmap, as described previously. The options supported for this command include 
-background color The background color for this bitmap. If this is empty (the default), 

background pixels will be transparent. 

-foreground color The foreground color for this image. The default is black. 


-data data The data that defines this image. This must be in the same format as an 
X Windows system bitmap file. 


-file filename A file containing the X-Bitmap data. 


The X Window system bitmap file is quite simple. It was designed to be included in C programs 
and looks like a piece of C code. The format is as follows. 


i## define name_width width 

if define name_height height 

static unsigned char name_bits[] = { 
datal, data2, 

} 


The good news is that this is simple and easy to construct. The bi tmap program on a UNIX system 
will let you construct an X-Bitmap file, or you can use the imagemagick or PBM utilities to convert an 
MS Windows or Mac bitmap file to an X-Bitmap file. 


OOOO nn — y»-> 
Example 20 


Script Example 


it Create and pack a canvas 
pack [canvas .c -background white -height 60 -width 100] 


i## This is the hourglass bitmap from the predefined bitmaps in 

i## the Tk 8.0 distribution: tk8.0/bitmaps/hourglass.bmp 

set hourglassdata { 

i## define hourglass_width 19 

if define hourglass_height 21 

static unsigned char hourglass_bits[] = { 
Oxff,Oxff,0x07,0x55,0x55,0x05,0xa2,0x2a,0xX03,0x66,0x15,0x01, 
Oxa2,0x2a,0x03,0x66,0x15,0x01,0xc2,0x0a,0x03,0x46,0x05,0x01, 
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0x82,0x0a,0x03,0x06,0x05,0x01,0x02,0x03,0x03,0x86,0x05,0x01, 
Oxc2,0x0a,0x03,0x66,0x15,0x01,0xa2,0x2a,0x03,0x66,0x15,0x01, 
Oxa2,0x2a,0x03,0x66,0x15,0x01,0xa2,0x2a,0x03,0xff,Oxff,0x07, 
Oxab,0xaa,0x02}; 

} 


i## Create a bitmap image from the hourglass data 
set bm Limage create bitmap -data $hourglassdata] 


i## And create a displayable canvas image item from that image. 
.c create image 50 30 -image $bm 


if And label the image.n 
.c create text 50 50 -text "bitmap image" 


Script Output 


bitmap image 


12.8.3 Photo Images 


The image data fora photo image may be PPM, PGM, or GIF. The data may be in binary form in a 
disk file or encoded as base64 data within the Tcl script. base64 encoding is a technique for converting 
binary data to printable ASCII with the least expansion. This format is used by all e-mail systems 
that support the MIME (Multipurpose Internet Mail Extensions) protocol (which most modern mail 
programs do). Strange as it sounds, the most portable way of converting a file from binary to base64 
encoding is to mail it to yourself, save the mail, and extract the data you want from the saved mail file. 

If you are running on a UNIX system, you may have the mmencode or mimencode program 
installed. These are part of the metamai 1 MIME mail support. 

The tcl 1ib (http://Tcllib.sf:net/) collection of useful tools is included in the ActiveTcl distribution 
and includes the base64 package. This package includes encode and decode functions within the 
base64 namespace that will convert data to and from base64 format within a script. 


package require base64 

set b64Stream [base64::encode $binaryData] 

The image create photo command supports several options. These include 
-data string The base64 encoded data that defines this image. 

-file filename A file that contains the image data in binary format. 


-format format The format for this image data. Tk will attempt to determine the type of image 
by default. The possible values for this option in version 8.4 are gif, pgm, 
and ppm. Tcl 8.6 adds support for PNG images. 


440 CHAPTER 12 Using the canvas Widget 


As with the image create bitmap command, this command creates a new command with the 
same name as the new image, which can be used to manipulate the image via the 7mageName cget 
and imageName configure commands. 

The photo type images support other subcommands, including the following. 


Syntax: jmageName copy sourcelmage ?options? 
Copy the image data from source!lmage to the image imageName. Options include: 
-from xl yl x2 y2_ The area to copy from in the source image. The coordinates 
define opposing corners of a rectangle. 


-to xl yl x2 y2 The area to copy to in the destination image. 
-shrink Shrink the image if necessary to fit the available space. 
-Zoom Expand the image if necessary to fit the available space. 


Syntax: imageName get x y 
Return the value of the pixel at coordinates x, y. The color is returned as three 
integers: the red, green, and blue intensities. 


Syntax: imageName put data?-to xl yl ?x2 y2?? 
Put new pixel data into an image object. 
data The data is a string of color values, either as color names 
or in #rgb format. By default, these pixels will be placed 
from the upper left corner, across each line, and then across 
the next line. 


-to xl yl x2 y2_ Declares the location for the data to be placed. If only x1, 
yl are defined, this is a starting point, and the edges of 
the image will be used as end points. If both x1, y1 and 
x2, y2 are defined, they define the opposing corners of a 
rectangle. 


The following example creates an image from base64 data, 
copies the data to another image, extracts some data (from the 
base of the T), and draws a box around the extracted data. In 
the extracted data, each pixel is grouped within curly braces and 
displayed as a red, blue, and green intensity value. The {0 0 0} 
pixels are black, and the {60 248 52} pixels are green. 


———————— eee ee ee eee 
Example 21 


Script Example 


i## Create a canvas 
canvas .c -height 100 -width 300 -background white 
pack .c 


if Define an image - in base 64 format 
set img { 
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RO1GODdhQAAWAKEAAP// /wAAADZANAD// ywAAAAAQAAWAAAC/oSPqcvtD60ctNqLs 
16h+w+G4ki WAWOmb6hqi 7AULbi JjU9kK3adHxyYtOBBoQjokfAm4GQQeawZBw6X8ri FH 
q9sqo/rZQY9aq4NK3wPllufdilE/ORjJ9mMSrNcoT5Hd/PIxb71XZ9d1xXOMh+Ne3CBh 
IZ+UX1IDR52KNggu0GBtToeF kJBWqZIJojml gKipp6uDoyABsrGxCr+sgC25FLO6Db 
W+kq8svr8bvbehtzxDyclOw7+9rsCwlDJos9TQlyrK2XnB3Nrb3r/f35EY4dskxtf 
k46rt50LP/uGZ8+7T8/fSz+Hjtk+duSM3RvBZV8/gsys3VI4TRyvYbXWBBQY jhXAJX 
Z61GmEhM4BEto8bQ5dkFewkyAMqU6VsSWKDZJk0a9q8i TNnhQIAQw== 

} 


if Create an image from the img data 
set i Limage create photo -data $img] 


i## Now, create a displayable canvas image item from the image 
.c create image 25 40 -image $i -anchor nw 


if Create an image with no data, 
set i2 Limage create photo -height 50 -width 70] 


$i2 put white -to 0 0 70 50 
## And copy data from the original image into it. 
$i2 copy $i -from 1 1 50 40 -to 10 10 60 50 


it Now display the image 
.c create image 140 40 -image $12 -anchor nw 


i## Display some of the values in the new image 
puts "Values from 24 24 to 29 31" 
for {set y 24} {$y < 31} tincr y} { 

for {set x 24} {$x < 29} {incr x} { 

puts -nonewline \ 

"[format "% 12s" [list [$i2 get $x $y]]]" 

} 

puts 


} 


## Draw an outline around the area we sampled: 
for {set x 24} {$x < 29} {incr x} { 

$i2 put (#FFF #FFF} -to $x 23 

$i2 put {#FFF #FFF} -to $x 30 


for {set y 24} {$y < 31} {incr y} { 
$i2 put (#FFF} -to 22 $y 


$i2 put {(#FFF} -to 23 $y 
$i2 put {(#FFF} -to 29 $y 
$i2 put {(#FFF} -to 30 $y 
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if And label the images. 

.c create text 25 5 -text "photo image 1" \ 
-font {helvetica 12} -anchor nw 

.c create text 140 5 -text "copied and \nmodified" \ 
-font {helvetica 12} -anchor nw 


Script Output 
Values from 24 24 to 29 31 
{0 0 0} {60 248 52} {60 248 52} {0 0 0} {0 0 0} 
{0 0 0} {60 248 52} {60 248 52} {0 0 0} {0 0 0} 
{0 0 0} {60 248 52} {60 248 52} {0 0 0} {0 0 0} 
{0 0 0} {60 248 52} {60 248 52} {0 0 0} {0 0 0} 
{60 248 52} {60 248 52} {60 248 52} {60 248 52} {0 0 0} 
{0 0 0} {0 0 0} {0 0 0} 
{0 0 0} {0 0 0} {0 0 0} 


12.8.4 Revisiting the del aybutton Widget 

The bitmaps used in the delayButton example are all predefined in the Tk interpreter. If you have 
a bitmap of your own you would like to use, you would have to define it in a data file using the X 
Window system bitmap format. For example, if the bitmap image is in a file named bitmap.xbm, the 
delayButton could be created with the following command. 


delayButton .f.bFile -bitmap @bitmap.xbm ... 


Tk has no method for defining canvas bi tmap item data in a script. Tk does allow you to define an 
image of type bitmap from data included in the script. The image command is the preferred way of 
dealing with images on canvases. 

Unfortunately, you cannot access the predefined bitmaps with the image command, though you can 
load the data from the distribution (under the TkDistribution/bitmaps directory), as was just done in. 

Following is a modified version of the delayButton procedure that uses an image instead of a 
bitmap and a script that creates its own bitmaps to display in the buttons. The code that executes 
within the delayButton namespace does not change. 

The info and warning bitmap data are taken from the files bitmaps/questhead.bmp and bitmaps/ 
warning.bmp. The data for the clockIcon is a base64 encoded GIF image. It may not be obvious 
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in the book, but the clock has a red body, a blue border, and yellow hands. The points to note in this 
version of the script are as follows. 


e The -bitmap options are replaced with - image options. 

e The bitmap objects are replaced by image objects. 

e The - foreground option is not supported in the canvasName create image command but is 
supported as a subcommand of the image object. 


————————————— eee eee 
Example 22 


Script Example 
i## Load the delayButton namespace code. 


source delayButton.tcl 


SMM Re 

## proc delayButton {delayButtonName args}-- 

if Create a delayButton icon that will evaluate a command when 
## «clicked and display an information label if the cursor 

# rests on it 


if Arguments 
if delayButtonName The name of this delayButton 


if args A list of -flag value pairs 
dt 
## Results 


if Creates a new delayButton and returns the name to the 
# calling script 
i## Throws an error if unrecognized arguments or required args 
if are missing. 
proc delayButton {delayButtonName args} { 
# define defaults 
set height 48 
set width 48 
set background gray80 
set highlight gray90 
set foreground black 
set text "" 
set commandl "" 
set command2 "" 
set image "" 
set font {Helvetica 10} 


i## =Step through the arguments. 

d# = =Confirm that each -option is valid (has a default), 
## and set a variable for each option that is defined. 

## = The variable for -foo is "foo". 
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foreach {option val} $args { 
set optName [string range $option 1 end] 
if {!Linfo exists $optName]} { 
error “Bad argument $option - \ 
must be one of Linfo locals]" \ 
"Invalid option" 
} 
set $optName $val 
} 


i## These arguments are required. 
set reqOptions [list -command1l -command2 -image] 


i## Check that the required arguments are present 
i## Throw an error if any are missing. 
foreach required $reqOptions { 
if {Llsearch -exact $args $required ] < 0} { 
error "delayButton requires a $required option" \ 
"Missing required option" 


} 


dt Create the canvas for this delayButton 
canvas $delayButtonName -height $height -width $width \ 
-background $background 


if Place the image in it. 
$delayButtonName create image [expr $width/2] \ 
[expr $height/2] -image $image 


if If there is text, it goes on the bottom. 
if {![string match $text ""]} { 
$delayButtonName create text [expr $width/2] \ 
[expr $height-1] \ 
-text $text -fill $foreground \ 
-font $font -anchor s 
} 


i## Bind the button click to evaluate the $command 

## «script in global scope 

bind $delayButtonName <ButtonPress-1> \ 
"::delayButton::scheduleCommand2 $delayButtonName" 

bind $delayButtonName <ButtonRelease-1> \ 
"::delayButton::invokeCommand1 $delayButtonName" 


if Bind the background to change color when the 
## «cursor enters 
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bind $delayButtonName <Enter> \ 
"$delayButtonName configure -background $highlight" 


i Bind the background to change color when the cursor 
i## leaves, and cancel any pending display of an info label. 
bind $delayButtonName <Leave> \ 
"$delayButtonName configure -background $background;\ 
::delayButton::cancelCommand2 $delayButtonName;" 


i Register the commands 
::delayButton::registerCommands $delayButtonName \ 
$commandl $command2 


i## And return the name 
return $delayButtonName 
} 


i## The following script shows how the delayButton} can be used 


i## makeMenu is the same as the previous procedure for creating 
i## an ad-hoc popup menu. 


proc makeMenu {args} { 

catch {destroy .m} 

menu . 
foreach item $args { 

.m add command -label $item 


} 
.m post [winfo pointerx .] [Lwinfo pointery .] 
} 


it Create images for info, clock and warning 
## Use bitmap data for info and warning, and 
i## =a base64 GIF image for the clock 


set info Limage create bitmap -data { 

if define info_width 8 

if define info_height 21 

static unsigned char info_bits[] = { 
Ox3c, Ox2a, 0x16, Ox2a, 0x14, 0x00, Ox00, Ox3f, 0x15, 
Ox2e, 0x14, Ox2c, 0x14, Ox2c, 0x14, Ox2c, 0x14, Ox2c, 
Oxd7, Oxab, 0x55 


td 


image create photo clockIcon -data { 
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ROIGODIhIAAgALMAANnZ20D/////AAAAADOZmZmZmf 8BAAMwAAUmZAMz 
ZP///IIIIIIIIIIIIII111 11 1 yYHSBAEAAAAALAAAAAAGACAAAAT/EA 
AY5KTVXgDAVULAAYOcVBJQaxVilBpARIYQQoFDT 1 rtCIEQEgIMZUAjJ 
63WjJEATCQGGAY 2ctNoZCCEhBDigkZMeISidgRACgxzQyEmPEGNQagKB 
hIQQBJRyOi PEGUSaQCAhHIYQBjZZOCDEGpSYOQSEgIYUAjJz1CjJEGpCQQ 
SEKIYOMhJjxBjJUGoCgYSEEAYOctI jxBiUmkAgISGEAY 2c9AgxBqUmEE 
hICGFALyc9QoxBqQkEEhKEGNDISYUSROghgIFBiBGEGNDIOY+QpQghx 
IDDGBOEGGGMAY 2c8gi BEBXxySmNMmCGEAY 2c5ggBh5x0GGMC I SQEGAYO 
ch4hxphzjU4TIJEhhAGN1] Ee lMeacUwZIZAHhGGPMEWLAAY 2ctAZCSAh 
hUCJEGNDISasJhJAQwoBGGjHGnHNOGOgkJIQwoJGTVjsDISSEAAcOct 
JqZyCEhBBggUZOWUOMhJAQAgwFGj Il ptSYROggMctUqLSRShjDnnFKIM 
ecOERCARE5ahRi 1SgAAJHJSOsaol QAQAQA7 

} 


set warning Limage create bitmap -data { 

if define warning_width 6 

i## define warning_height 19 

static unsigned char warning_bits[] = { 
OxOc, 0x16, Ox2b, 0x15, Ox2b, Ox15, Ox2b, 0x16, OxOa, 
Oxl6, OxOa, 0x16, Ox0a, Ox00, 0x00, Oxle, Ox0a, Oxl6, 
Ox0a} 

}] 


it Create the three buttons and grid them. 

delayButton .bl -image $info -text "INFO" \ 
-commandl {tk_messageBox -type ok -message "Information"} \ 
-command2 {makeMenu "Tcl Info" "Tk Info" "Expect Info"} 


delayButton .b2 -image clockIcon \ 
-co {tk_messageBox -type ok \ 
-message [clock format [clock seconds]]} \ 
-command2 {makeMenu "Time in London" \ 
"Time ji ew York" "Time in Chicago"} 


fal 
he 


Po 


delayButton .b3 -image $warning \ 
-commandl {treportLatestAlert} \ 
-command2 {reportAllAlerts} \ 
-background #AAA -foreground #FFF -highlight #888 


fa 


Po 


grid .b1l .b2 .b3 


Script Output 
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The behavior is the same with the - bitmap version and the - image version. The - image version 
of this widget needs more setup but is more versatile. 


12.9 BOTTOM LINE 


e The canvas widget creates a drawing surface. 

e The canvas widget returns a unique identifier whenever a drawable item is created. 

e Drawable items may be associated with one or more tag strings. 

e The coordinates of a drawable item can be accessed or modified with the canvasName coords 
command. 
Syntax: canvasName coords tagOrId ?x1l yl1?... ?xn yn? 

e A drawable item can be moved on a canvas with the canvasName move command. 
Syntax: canvasName move tagOrId xoffset yoffset 

e The space occupied by a drawable item is returned by the canvasName bbox command. 
Syntax: canvasName bbox tagOrId 

e A list of items that match a search criterion is returned by the canvasName find command. 
Syntax: canvasName find searchSpec 

e A drawable item’s location in the display list can be modified with the canvasName raise 
command and canvasName | ower command. 
Syntax: canvasName raise tagOrId? abovetagOrId? 
Syntax: canvasName lower tagOrId? belowtagOrId? 

e A list of available fonts is returned with the font families command. 
Syntax: font families ?-displayof windowName 

e The horizontal space necessary to display a string in a particular font is returned by the font 
measure command. 
Syntax: font measure font ?-displayof windowName? text 

e The closest match to a requested font is returned by the font actual command. 
Syntax: font actual font ?-displayof windowName? 

e Actions can be bound to events on a widget with the bind command. 
Syntax: bind widgetName eventType script 

e Actions can be bound to events on a drawable item within a canvas widget, with the canvasName 
bind command. 
Syntax: canvasName bind tagOrId eventType script 

e Two-color (bitmap) and multicolor (photo) images can be created with the image create 
command. 


Syntax: image create type ?name? ?options? 
e Images can be deleted with the image delete command. 
Syntax: image delete name ?name? 


e Information about an image is returned by the image height, image width, andimage type 
commands. 
Syntax: image height name 
Syntax: image width name 
Syntax: image type name 
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e A list of images currently defined in a script is returned by the image names command. 
Syntax: image names 

e Photo image pixel data can be copied from one image to another with the imageName copy 
command. 
Syntax: imageName copy sourceImage? options? 

e Photo image pixel data can be accessed or modified with the imageName get and imageName put 
commands. 
Syntax: imageName get x y 
Syntax: imageName put data?-to xl yl ?x2 y2?? 

e The canvas create bitmap command and the image create bitmap command are not the 
same but can be used to achieve equivalent results. 


Canvas create bitmap Image create bitmap 


Can access internal bitmaps Can use data defined within a script 
Can reference a data file via | Can reference a data file via 
@filename -file 

Can modify foreground via: Can modify foreground via: 
cvsName create bitmap \ imageHandle configure \ 
-foreground $newcolor -foreground $newcolor 


12.10 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range ___ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under a 
minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 

chapter. They may require reading a man page or making a web search. A short script of 

1-50 lines should fulfill the exercises, which may take 10-20 minutes each to complete. 

800-399 Long exercises may require reading other material or writing a few hundred lines of code. 

These exercises may take several hours to complete. 


e 100 Can an object drawn on a Tk canvas have more than one tag? 
e 101 What command would draw a blue line from 20,30 to 50,90 on a canvas named .c? 
e 102 How many colors can be included in a canvas bitmap object? 


e 103 What command would cause all canvas graphic objects on a canvas named .c with the tag 
red to turn red when a cursor passes over them? 
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104 What command will cause keyboard events to be sent to a label named . 1? 
105 Can a canvas be linked with a scrollbar? 

106 What command will create an image object? 

107 What command will display an image object? 

108 Can you access the data in a single pixel of a Tk image object? 


109 If an application is running on a 1024 x 768 pixel display, what command would resize the 
application to fill the display? 


110 What command will return the height of a window? 


200 Write a script that creates a canvas and draws a 20 x 30 pixel blue rectangle with a 
5-pixel-wide green border, a red oval with a 2-pixel-wide yellow border, and a 3-pixel-wide red 
line that connects them. 


201 Create a bouncing ball animation by creating a canvas and an oval and changing the oval 
location every 10 milliseconds. Allow the bouncing ball to only bounce to 90% of the height of 
the starting location, to simulate a bouncing ball settling down. 


202 Modify the delaybutton example in Section 12.6 to require text instead of a bitmap, and size 
the button to match the text, instead of using a fixed-size button. 


203 Modify the delaybutton example in Section 12.6 to require a-he|1pText option, and 
automatically attach the help balloon described in Section 12.7 when the delaybutton is 
created. 


204 Lemon juice is a classic invisible ink. It dries invisibly until the paper is heated and the sugars 
in the lemon juice caramelize and turn brown. Write a Tcl script to simulate this by writing white 
text on a white background, and then slowly change the color using the itemconfigure 
command. 


205 Modify the bouncing star example in Section 12.4.3 to include several non-moving circles. 
Highlight whichever circle is closest to the star as the star moves around. 


206 Write a script that examines each pixel in an image object and counts the occurrences of 
pixels of different brightness values (referred to as “histogramming an image’’). Display the results 
by printing the brightness value and count for any non-zero count. 


300 Add bindings to the display in problem 201 so that you can “grab” the rectangle or oval by 
placing the cursor on it and holding down the left mouse button, and “drag” it by moving the 
cursor while the button is depressed. 


301 Modify the script in problem 301 to update the line coordinates to always connect the two 
nearest edges of the rectangle and oval. 


302 Create a simple “paint” package that will have radio buttons for select-drawing a rectangle or 
oval, and will allow a user to click on a location on the screen and drag a corner to define the size 
of the rectangle or oval. 


450 CHAPTER 12 Using the canvas Widget 


e 303 The winfo class command will return the type of a window (Button, Frame, and so on). 
Use this command to write a recursive procedure that will place the names of all windows in an 
application into a tree data structure. Use a nested dict to hold the data as described in Chapter 6. 


¢ 304 Write a Tk procedure that will display the elements in a tree data structure with each element 
on a single line, and indentation to denote how many levels deep a tree element is. You may need 
scrollbars to view an entire tree. The output should resemble the following. 


.buttonFrame 
.buttonFrame.file 
.buttonFrame.edit 
.buttonFrame. view 

.dataFrame 
.dataFrame.canvas 
.dataFrame. label 


e 305 Modify the script created for problem 206 to display the results as a bar chart. Scale the bars 
so that the longest is 90% of the canvas size, and use a scrollbar to display all bars. 


CHAPTER 


The text Widget and 
htmllib 


The message, label, and entry widgets are useful for applications with short prompts and small 
amounts of data to enter. That is, for applications that resemble filling out a form. However, some 
applications need to allow the user to display, enter, or edit large amounts of text. The text widget 
supports this type of application. The text widget supports the following. 


e Emacs-style editing 

e Arrow-key-style editing 

e Scrollbars 

e Multiple fonts in a single document 

e Tagging a single character or multiple-character strings (in a similar manner to the way tags are 
applied to canvas objects) 

e¢ Marking positions in the text 

e Inserting other Tk widgets or images into the text display 

e Binding events to a single character or a multiple-character string 


Stephen Uhler used the text widget to construct the htm]_library for rendering HTML documents. 
This is not part of the Tcl/Tk distribution but can be found on the companion website and is available 
via ftp at: 

http://noucorp.com/tcl/utilities/htmllib/himllib-rel_O_3_4.zip 

This pure Tcl package will render html text and provides hooks for links and images. This chapter 
introduces the text widget and the htm! library. 


}.1 OVERVIEW OF THE text WIDGET 


An application may create multiple text windows, which can be displayed in either a top-level window, 
frame, canvas, or another text widget. The content of a text widget is addressed by line and character 
location. The text widget content is maintained as a set of lists. Each list consists of the text string to 
display, along with any tags, marks, image annotations, and window annotations associated with this 
text string. 

The text widget displays text longer than the width of the widget in one of two ways. It can either 
truncate the line at the edge of the widget or wrap the text onto multiple lines. The widget can wrap the 
text at a word or character boundary. 

When text wraps to multiple lines, the number of lines on the display will be different from the 
number of lines in the internal representation of the text. When referencing a location within the text 
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widget, the line and character position refers to the internal representation of the text, not what is 
displayed. 

When a scrollbar is connected to the text widget, the user can modify which lines are displayed 
on the screen. This does not affect the content of the text widget, and the line and character positions 
still reflect the internal representation of the text, not the displayed text. For example, if the user scrolls 
to the bottom of a document so that the top line is the fiftieth line of the document, the line number is 
still 50, not 1. 

A text string can have a tag associated with it. Tags in a text widget are similar to tags in the 
Canvas object. You can apply zero or more tags to an item of text, and apply a given tag to one or 
more items of text. Tags are used to mark sections of text for special treatment (different fonts, binding 
actions, and so on). Tags are discussed in more detail later in the chapter. 

A text widget can also have marks associated with it. Marks are similar to tags, except that where 
tags are associated with a text string, a mark is associated with a location in the text. You can have only 
a single instance of any mark, but you can have multiple marks referring to a single location. Marks 
are used to denote locations in the document for some action (inserting characters, navigating with a 
mouse, and so on). Marks are discussed in more detail later in the chapter. 


13.1.1 Text Location in the text Widget 

The text widget does not allow you to place text at any location, the way a canvas widget does. A 
text widget “fills” from the top left, and you can address any position that has a character defined at 
that location. If a program requests a position outside the range of available lines and characters, the 
text widget will return the nearest location that has a character defined (usually the end). Tcl uses a 
list to define the index that describes a location in the text widget. 


position ?modifierl modifier2...modifierN? 


The position field may be one of the following. 
line.character — The line and character that define a location in the internal 

representation of the text. Lines are numbered starting from 
1 (to conform to the numbering style of other UNIX 
applications), and character positions are numbered starting 
from 0 (to conform to the numbering style of C strings). 
The character field may be numeric or the word end. 
The end keyword indicates the position of the newline 
character that terminates a line. 


@x.y The x and y parameters are in pixels. This index maps to 
the character with a bounding box that includes this pixel. 

markID The character just after the mark named markID. 

tagID.first The first occurrence of tag tagID. 

tagID.last The last occurrence of tag tagID. 

windowName The name of a window that was placed in this text widget 


with the window create widget command. 
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imageName The name of an image that was placed in this text widget 
with the image create widget command. 
end The last character in the text widget. 
The modifier fields in an index may be one of: 

t+num chars 

-num chars 

t+num lines 

-num lines 


The 1 ocation moves forward or backward by the defined number of characters or 
lines. The plus symbol (+) moves the ]1ocation forward (right or down), and the 
minus symbol (—) moves the | ocation backward (left or up). 


linestart 

lineend 

The index refers to the beginning or end of the line that includes the location 
index. NOTE: {1.0 1ineend} is equivalent to {1.end} and {1.0 linestart} is 
equivalent to {1.0}. 

wordstart 

wordend 

The index refers to the beginning or end of the word that includes the location 
index. 


Index Examples 
The following are examples of valid and invalid index descriptions. 


0.0 

Not a valid index because line numbers start at 1. This will be mapped to the 
beginning of the text widget, index 1.0. 

{.b wordend} 

If a letter follows window .), this refers to the location just before the first space 
after the .b window. 

If window .b is at the end of a word, this refers to the location just after the space 
that follows window .b. 

1.0 lineend 

This is not a valid index; it is not a list. 

[list mytag.first lineend -10c wordend] 

Sets the index to the end of the word that has a letter 10 character positions from the 
end of the line that includes the first reference to the tag mytag. Note that the 
index is evaluated left to right, as follows. 
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Find the first occurrence of the tag mytag. 
Move to the end of the line. 

Count back 10 characters. 

Go to the end of the word. 


ONS 


13.1.2 Tag Overview 

The tag used in a text widget is similar to the tag used with the canvas object. A tag is a string of 
characters that can be used to identify a single character or text string. A tag can reference several text 
strings, and a text string can be referenced by multiple tags. 

A tag’s start and end locations define the text string associated with it. Note that the tag is associated 
with a location, not the character at a location. If the character at the location is deleted, the tag moves 
to the location of the nearest character that was included in a tagged area. If all the characters associated 
with a tag are deleted, the tag no longer exists. 

Manipulating portions of text (setting fonts or colors, binding actions, and so on) is done by iden- 
tifying the text portion with a tag and then manipulating the tagged text via the textWidget tag 
configure command. For instance, the command 


$textWidget tag configure loud -font [times 24 bold] 


will cause the text tagged with the tag 1 oud to be drawn with large, bold letters. All text tagged 1 oud 
will be displayed in a large, bold font. 

The sel tag is always defined in a text widget. It cannot be destroyed. When characters in the 
text widget have been selected (by dragging the cursor over them with the mouse button depressed), 
the sel tag will define the start and end indices of the selected characters. The se] tag is configured 
to display the selected text in reverse video. 


13.1.3 Mark Overview 
Marks are associated with the spaces between the characters, instead of being associated with a char- 
acter location. If the characters around a mark are deleted, the mark will be moved to stay next to the 
remaining characters. Marks are manipulated with the textWidget mark commands. 
A mark identifies a single location in the text, not a range of locations. 
A mark can be declared to have gravity. The gravity of a mark controls how the mark will be 
moved when new characters are inserted at a mark. The gravity may be one of: 
left The mark is treated as though it is attached to the character on the left, and 
any new characters are inserted to the right of the mark. Thus, the location 
of the mark on a line will not change. 


right The mark is treated as though it is attached to the character on the right, 
and new characters are inserted to the left of the mark. Thus, the location 
of the mark will be one greater character location every time a character is 
inserted. 
The following two marks are always defined. 
insert The location of the insertion cursor. 


current The location closest to the mouse location. Note that this is not updated 
if the mouse is moved with button | depressed (as in a drag operation). 
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13.1.4 Image Overview 

Images created with the image create command (covered in Chapter 12) can be inserted into a text 
widget. The annotation that defines an image uses a single character location regardless of the height 
or width of the image. The textWidget image create command can insert multiple copies of an 
image into a text widget. Each time an image is inserted, a unique identifier will be returned that can 
be used to refer to this instance of the image. 


13.1.5 Window Overview 


The textWidget window create command will insert a Tk widget such as a button, canvas, or 
even another text widget into a text widget. Only a single copy of any widget can be inserted. If 
the same widget is used as the argument of two textWidget window create commands, the first 
occurrence of the widget will be deleted, and it will be inserted at the location defined in the second 
command. 


13.2 CREATING A text WIDGET 


Text widgets are created the same way as other widgets, with a command that returns the specified 
widget name. Like other widgets, the text widget supports defining the height and width on the 
command line. Note that the unit for the height and width is the size of a character in the default font, 
rather than pixels. You can determine the font being used by a text widget with the configure or 
cget widget command. (See Chapter 11.) 
Syntax: text textName ?options ? 
Create a text widget. 
textName The name for this text widget. 
?options?Some of the options supported by the text widget are: 
-state state 
Defines the initial state for this widget. May be one of: 
normal The text widget will permit text to be edited. 
disabled The text widget will not permit text to be 
edited. This option creates a display-only 
version of the widget. 
-tabs tabList 
Defines the tab stops for this text widget. Tabs are 
defined as a location (in any screen distance format, as 
described in Chapter 11) and an optional modifier to 
define how to justify the text within the column. The 
modifier may be one of: 
left Left justify the text. 
right Right justify the text. 
center Center the text. 
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numeric Line up a decimal point, or the least significant 
digit at the tab location. 
-wrap style 


Defines how lines of text will wrap. May be one of: 


none Lines will not wrap. Characters that do not fit 
within the defined width are not displayed. 

word Lines will wrap on the space between words. 
The final space on a line will be displayed as a 
newline, rather than leave a trailing space on 
the line before the wrap. Words are not wrapped 
on hyphens. 


char Lines will wrap at the last location in the text 

widget, regardless of the character. This is the 
default mode. 

-spacingl distance 

Defines the extra blank space to leave above a line of 

text when it is displayed. If the line of text wraps to 

multiple lines when it is displayed, only the top line will 

have this space added. 

-spacing2 distance 


Defines the extra blank space to leave above lines that 
have been wrapped when they are displayed. 
-spacing3 distance 

Defines the extra blank space to leave below a line of 
text when it is displayed. If the line of text wraps to 
multiple lines when it is displayed, only the bottom line 
will have this space added. 


————— OOO eee eee ee eee 
Example 1 


Script Example 


i## Create and grid the text widget 
set txt [text .t —height 12 —width 72 —background white \ 

—tabs {2i right 2.47 left 4.61 numeric} —font {helvetica 12}] 
grid $txt 


if Insert several lines at the end location. Each new line 
if becomes the new last line in the widget 


$txt insert end "The next lines demonstrate tabbed text\n" 
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txt insert end "noTab \t Right Justified \t\ 
Left Justified \t Numeric\n" 


txt insert end "\n" 
txt insert end "linel \t columnl \t column2 \t 1.0\n" 


txt insert end "line2 \t columnl text \t column2\ 
text \t 22.00\n" 


txt insert end "line3 \t text in column] \t text\ 
for column2 \t 333.00\n" 


## Insert a few lines at specific line locations 
i## to demonstrate some location example 


$txt insert 1.0 "These lines are inserted last, but are\n" 
$txt insert 2.0 "inserted at the\n" 

$txt insert 2.end " beginning of the text widget\n" 

$txt insert {3.5 linestart} "so that they appear first.\n" 


Script Output 


These lines are inserted last, but are 
inserted at the beginning of the text widget 
so that they appear first. 


The next lines demonstrate tabbed text 
noTab Right Justified Left Justified Numeric 


line1 column1 column2 1.0 
line2 column1 text column2 text 22.00 
lined text in column text for column2 333.00 


13.3 Text WIDGET SUBCOMMANDS 


This section describes several of the more useful subcommands supported by the text widget. See 
the on-line documentation for your version of Tk for more details, and to see if other subcommands 
are implemented in the version you are using. The dump subcommand provides detailed information 
about the content of the text widget. Thus, it is very seldom used in actual programming, but can 
be very useful when debugging a complex display that’s not doing quite what you expect. The dump 
subcommand is used in the following discussion of the text widget, as we examine how text strings, 
marks, and tags are handled by the text widget. 
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The dump subcommand returns a list of the text widget’s content between two index points. 
Each entry in the list consists of sets of three fields: identifier, data, and index. The iden- 
tifier may have one of several values that will define the data that follows. The data field will 
contain different values, depending on the value of the identifier. The index field will always be 
a value in line.char format. The values of identifier and the associated data may be one of the 


following. 


Lagon 


tagoff 


mark 


image 


window 


text The following data will be text to be displayed on the text widget. If 
there are multiple words in the text, the text will be grouped with curly 
braces. 


Denotes the start of a tagged section of text. The data associated with 
this identifier will be a tag name. The index will be the location at which 
the tagged text starts. 

Denotes the end of a tagged section of text. The data associated with 
this identifier will be a tag name. The index will be the location at which 
the tagged text ends. 

Denotes the location of a mark. The data associated with this identifier 
will be a mark name. The index will be the location to the right of the 
mark, 

Denotes the location of an image to be displayed in the text widget. 
The index will be the index of the character to the right of the image. 
Denotes the location of a window to be displayed in the text widget. The 
index will be the index of the character to the right of the window. 


13.3.1 Inserting and Deleting Text 
The insert subcommand will insert one or more sets of text into the text widget. Each set of text 
can have zero or more tags associated with it. 


Syntax: textName insert index text ?tagList? ?moreText? ?morelags? ?...? 


Insert text into text widget. 


textName The name of the text widget. 


index The index at which to insert this text, formatted as 
described in Section 13.1.1 
text A string of text to insert. If this text includes embedded 


newlines (\n), it will be inserted as multiple lines. 


tagList  Anoptional list of tags to associate with the preceding text. 


The following example creates a text widget, inserts three lines of text, and displays a formatted 
dump of the text widget content. Notice the foreach command with three arguments in a list to step 
through the dump output. The ability to use a list of arguments to a foreach command was added in 
Tcl revision 7.4. The foreach with a list of iterator variables is a useful construct for stepping through 
data formatted as sets of items, instead of as a list of lists. 
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$$ 
Example 2 
Script Example 
text .t —height 5 —width 60 —background white \ 
—font {helvetica 12} 
grid .t 


.t insert end "This text is tagged ’TAG1’. " TAG1 

.t insert end "This is on the same line, ’TAG2’\n" TAG2 
.t insert end \ 
"The linefeed after ’TAG2’ creates a new line.\n" 


-t insert 2.0 \ 
"Line 2 becomes 3 when this is inserted at 2.0\n" \ 
NSERTED 


set textDump [.t dump —all 1.0 end ] 
puts "Lformat "%-6s %-45s %4s\n" ID DATA INDEX]" 
foreach {id data index} $textDump { 

puts "[format {%-6s %-45s %4s} \ 
id [string trim $data] $index]" 


} 

Script Output 
ID DATA INDEX 
tagon TAG1 1.0 
text This text is tagged ’TAG1’. 1.0 
tagoff TAG1 1.28 
tagon TAG2 1.28 


R 
iS) 
foe} 


text This is on the same line, ’TAG2’ 

tagoff TAG2 

tagon INSERTED 

text Line 2 becomes 3 when this is inserted at 2.0 
tagoff INSERTED 

text The linefeed after ‘TAG2’ creates a new line. 
mark insert 

mark current 

text 


PP PW WY DYDD 
ee er rr 
oo o0o00dUcCOlUhUlO 


This text is tagged 'TAG1'. This is on the same line, 'TAG2 
Line 2 becomes 3 when this is inserted at 2.0 


The linefeed after 'TAG2' creates a new line 
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In the previous example, all lines are shorter than the width of the text widget. Since none of the 
lines wrap, the text widget display resembles the internal representation. The first line of the example 
inserts a line with the text This text is tagged ‘TAG1’. at the end of the text widget. Since there was 
no text in the widget, the end was also the beginning. The dump shows that tag TAG] starts at index 
1.0 and ends at index 1.28. The text also starts at index 1.0. 

Note that the second set of text is also inserted onto line 1. This is because the first set of inserted 
text did not have a newline character to mark it as terminating a line. The second set of text has a 
newline character at the end, which causes the next line to be inserted at index 2.0. However, the 
last insert command inserts text at location 2.0 and terminates that text with a newline, pushing 
the line that was at index 2.0 down to index 3.0. 

The del ete subcommand deletes the text between two locations. 

Syntax: textName delete startIndex ?endIndex? 
Remove text from a text widget. 
startIndex The location at which to start removing characters. 
?endIndex? If endIndex is greater than start Index, delete the 
characters after start Index to (but not including) the 
character after end Index. If endIndex is less than 
start Index, no characters are deleted. If endIndex is 


not present, only the character after start Index is 
deleted. 


if Clear all text in a widget 
$textWidget delete 1.0 end 


13.3.2 Searching Text 
A script can search for text within a text widget using the textWidget search subcommand. 
This command will search forward or backward from an index point or search between two index 
points. 
Syntax: textName search ?options? pattern startIndex ?endIndex? 
textName  Thename of the text widget. 
search Search the content of this text widget for text that matches 
a particular pattern. 
?options? Options for search include: 
Search Direction These are mutually exclusive 


options. 

- forwards The direction to search from the 
startIndex. 

-backwards 

Search Style These are mutually exclusive 


options. The default search style is to 
use g1ob rules. 
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-exact Search for an exact match. 

-regexp Use regular expression rules to match 
the pattern to text. 

-nocase Ignore the case when comparing 
pattern to the text. 

Other Options These are not mutually exclusive 
options. 


-count varName The -count option must be followed 
by a variable name. If the search is 
successful, the number of characters 
matched will be placed in varName. 


ie Signifies that this is the last option. 
The next argument will be interpreted 
as a pattern, even if it starts with a “-”, 
and would otherwise be interpreted as 
an option. As with the switch 
command, it is good style to use the 
“- -”Option whenever you use the 
search subcommand. This will 
ensure that your code will not generate 
an unexpected syntax error if it is used 
to search for a string starting with a 


pattern A pattern to search for. May be a g10b or regexp pattern, 
or a text string. 


startIndex The location in the text widget to start searching from. 
?endIndex? An optional location in the text widget to stop searching. 


$$$ Aaa 
Example 3 
Script Example 

i## Create and pack a text widget 

text .t —height 5 —width 68 —font {times 14} 

grid .t 


.t tag configure courier —font {courier 14 } 


if Insert some text 

.t insert end "The default style for the " 
.t insert end "search" courier 

.t insert end " command is to use" 

.t insert end glob " courier 

.t insert end "rules.\n" 
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insert end "The" 
insert end " —regexp " courier 
insert end \ 
"flag will treat the pattern as a regular expression\n" 
insert end "and, using the" 
insert end " —exact " courier 
insert end "flag will match an exact string." 
i## =6"Exact" doesn’t exist in this text, search will return "" 
set pos \ 
[.t search —exact —count matches — "Exact" 1.0 end] 


’ 


puts "Position of ’Exact 


dt 
if The two different fo 
set pos \ 


ts 


: 


s *$pos’ 


"exact flag" does exist. This will match 11 characters 


do not matter. 


[.t search —exact —count matches —- "—exact flag" 1.0 end] 
puts "Position of ’—exact’: $pos matched $matches chars" 
i## This regular expression search also searches for "—e" 
i## followed by any characters except a space 
## It will match to "—exact" 
set pos \ 

[.t search —regexp —count matches — {-e[* ]+} 1.0 end] 
puts "Position of ’-e\[* \]+’: $pos matched $matches chars" 
i## This is an error — the lack of the "——" argument causes the 
if search argument "—e[* ]*" to be treated as a flag. 
set pos [.t search —regexp —count matches {—eL~ ]x*} 1.0 end] 
puts "This line is not evaluated 


Script Output 
Position of ‘Exact’ is ’’ 
Position of ‘—exact’: 3.15 
Position of 
Error in 


matched 11 chars 


‘-e[*~ ]+’: 3.15 matched 6 chars 
startup script: bad switch "—-e[” ]*": 


must be —-, 


—all, —backward, —count, 


—nocase, —nolinestop, —overlap, —regexp, 


while executing 


elide, 


forward, 
or —strictlimits 


exact, 


".t search —regexp —count matchchars {—e[* ]*} 1.0 end" 
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The default style for the search command is to use glob rules. 
The -regexp flag will treat the pattern as a regular expression 


and, using the -exact flag will match an exact string. 


13.3.3 The mark Subcommands 

The textName mark subcommands are used to manipulate marks in the text widget. Marks are 
used when you need to remember a particular location in the text. For instance, you can use marks to 
define an area of text to highlight, for a cut-and-paste operation, and so on. The textName mark set 


command defines a mark. 


Syntax: textNamemark set markName index 
Set a mark in the text widget textName. 


markName The name to assign to this mark. 
index The index of the character to the right of the mark. 


$$ 
Example 4 
#f Put a mark at the beginning of the first three lines 
i## The marks are named start_l, start_2, etc 
for {set line 1} {$line <= 3} {incr line} { 
$textWidget mark set start_$line $line.0 


| 
The textName mark unset command will remove a mark. 
Syntax: textName mark unset markName ?... markNameN? 
Remove a mark from the text widget textName. 
markNamex The name or names of the mark to remove. 
_____ 
Example 5 


if Remove start_l, start_2 and start_3 marks 
for {set line 1} {$line <= 3} {incr line} { 
$textWidget mark unset start_$line 
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You can obtain a list of all marks defined in a text widget with the textName mark names 
command. 


Syntax: textName mark names 
Return the names of all marks defined in the text widget textName. 


$$ RaA@o£$ $a 
Example 6 
if Remove all start_* marks 
foreach mark [$textWidget mark names] { 
if {[string first start. $mark] == 0} { 
$textWidget mark unset \$mark\\ 


You can search for marks before or after a given index position with the textName mark next 
and textName mark previous commands. 


Syntax: textNamemark next index 


Syntax: textName mark previous index 
Return the name of the first mark after (next) or before (previous) the index 
location. 


index The index from which to start the search. 


eee ee eee 
Example 7 


Script Example 


i## Create a text widget for example 
pack [set textWidget [text .t]] 


## Put a mark at the beginning of the first three lines 

i## The marks are named start_l, start_2, etc 

for {set line 1} {$line <= 3} {incr line} { 
$textWidget mark set start_$line $line.0O 

} 


i## Step through the marks in a text widget 
## Start at the beginning 
set index 1.0 
while {$index ne ""} { 
set index [$textWidget mark next $index] 
puts "Index is: $index" 


} 
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Script Output 


Index is: start_1 
Index is: insert 
Index is: current 
Index is: start_3 
Index is: start_2 
Index is: 


The next example shows how marks appear in a text widget. 


eee 
Example 8 


Script Example 
grid [text .t —height 5 —width 60 —font {helvetica 12}] 


.t insert end "A mark will be set in this line,\n" 
.t insert end "as shown by dump" 


.t mark set demoMark 1.0 


puts "The first mark is: [.t mark next 1.0]" 
puts "The last mark is: [.t mark previous end]" 


set textDump [.t dump —all 1.0 end ] 


puts "[Lformat "%—-7s %-40s %6s\n" ID DATA INDEX]" 


foreach {id data index} $textDump { 
puts "[format {%-7s %-40s %6s} $id [string trim $data] $index]" 


Script Output 


The first mark is: demoMark 
The last mark is: current 


ID DATA INDEX 
mark demoMark 1.0 
text A mark will be set in this line, 1.0 
text as shown by dump 2.0 
mark insert 2.16 
mark current 2.16 
text 2.16 


A mark will be set in this line, 
as shown by dump 
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13.3.4 Tags 
Many of the interesting things that can be done with a text widget are done with tags. Tags define text 
that should be displayed in different fonts or colors, text with a highlighted background, text bound to 


an event, and so on. 


Creating and Destroying Tags 

Tags can be attached to text when the text is inserted, as shown in the example in section 13.2 or they 
can be added later with the textName tag add command. The textName tag remove command 
will remove a tag from a specific set of characters, and the textName tag delete command will 
remove all occurrences of a tag. 


Syntax: textName tag add tagName startIndexl ?endl? ?start2 ... endN? 
textName The text widget that will contain the tag. 
tag add Add a tag at the defined index points. 


startIndex ?end? The tag will be attached to the character at 
startIndex and will contain all characters up to 
but not including the character at end. If the end is 
less than the startIndex, or if the startIndex 
does not refer to any character in the text widget, 
no characters are tagged. 


—_——— ee eee 
Example 9 


## Tag the first letter of the page 
$textWidget tag add "firstLetter" 1.0 1.1 


= 
Syntax: textName tag remove tagName startIndexl ?endl? ?start2 ... endN? 
textName The text widget that contains the tag. 
tag delete Remove tag information for the named tags from 


characters in the ranges defined. 
tagName The names of tags to be removed. 


startIndex ?end? The range of characters from which to remove the 
tag information. 


———————— eee eee 
Example 10 


if Remove the firstLetter tag on the first letter 
$textWidget tag remove “firstLetter" 1.0 1.1 
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Syntax: textName tag delete tagName ?...tagnameN? 
textName The text widget that contains the tag. 


tag delete Delete all information about the tags named in this 
command. 


tagNamex The names of tags to be deleted. 


_.)]—_$££§$$§$§$§$§$§$§$§$ 
Example 11 

if Clear all tags in this widget 

## NOTE: "tag names" is described in the next section 

# Pre Tcl 8.5 

# eval $textWidget tag delete [$textWidget tag names] 

## Tcl 8.5 and newer 

$textWidget tag delete «[$textWidget tag names] 


Finding Tags 

Your script can get a list of tags that have been defined at a particular location, a range of locations, 
or an entire text widget. You can also retrieve a list of locations that are associated with a tag. 
Multiple tags can reference the same location in a text file. For instance, the first character of a para- 
graph may be in a different font, tagged to show that it is the start of a keyword, and tagged as the 
first character after a page break. You can obtain a list of the tags at a location with the tag names 
command. 


Syntax: textName tag names index 
textName The text widget that contains the tags. 
tag names Return a list of all tags defined at index. 
index The index point to check for tags. 


————————————————— eee eee ee eee 
Example 12 


i## Display the tags at the start of line 2: 
puts [$textWidget tag names 2.0] 


When you are processing the content of a text widget, you may want to step through the widget 
looking at tags in the order in which they appear. The next range and prevrange commands will step 
through a text widget, returning the index points that fall within the requested range of characters. 

Note that the prevrange and nextrange commands expect the start and end locations in the 
opposite order. For the prevrange command, startIndex is greater than endIndex, whereas for 
nextrange the endIndex is greater than start Index. 
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Syntax: textName tag nextrange tagName startIndex ?endIndex? 


Syntax: textName tag prevrange tagName startIndex ?endIndex? 


textName The text widget that contains the tags. 

tag nextrange Return the first index defined after 
startIndex but before endIndex. 

tag prevrange Return the first index defined before 
startIndex but after endIndex. 

tagName The name of the tag to search for. 

startIndex endIndex The index points that defined the boundaries 


for the search. 


$$$ 
Example 13 
Script Example 
i## Create a text widget for example 
set textWidget [text .t —font {helvetica 12} \ 
—height 4 —width 20] 
grid $textWidget 
if Add tagged and untagged text text 
for {set i 0} {$i < 3} {incr i} { 
textWidget insert end "$i ——" "myTag" 
textWidget insert end "—$i\n" 
} 


# Initialize the "current" mark to the start of text 
$textWidget mark set current 1.0 


if Find the next range of the tag "myTag" after current 
set tagRange [$textWidget tag nextrange "myTag" current] 


## Loop until the nextrange returns an empty string 
while {![£string match $tagRange ""J} { 

if Do something interesting with the tag data here 
puts "Range for myTag: $tagRange" 


i## Set the current mark to the end of the tagged area 
$textWidget mark set current [lindex $tagRange 1] 


if Find the next tagged range 
set tagRange [$textWidget tag nextrange "myTag" current] 
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Script Output 


Range for myTag: 
Range for myTag: 


wner 
ooo 
wne 
ans 


Range for myTag: 


The tag ranges command will return a list of all index ranges a tag references. 


Syntax: textName tag ranges tagName 
textName The text widget that contains the tags. 


tag ranges Return a list of index ranges that have been tagged with 
tagName. 


tagName The name of the tag to search for. 


OOOO nn — y= 
Example 14 


Script Example 


i## Create a text widget for example 
grid [set textWidget [text .t]] 


if Add tagged and untagged text 

for {set i O}{$i < 3} {incr 7} { 
$textWidget insert end "$i ——" "myTag" 
$textWidget insert end "—$i\n" 


} 


set tagRanges [$textWidget tag ranges "myTag"] 
puts "The tagged ranges are: $tagRanges" 
foreach {start end} $tagRanges { 
puts "‘[$textWidget get $start $end]’ is tagged" 


} 


Script Output 


The tagged ranges are: 1.0 1.4 2.0 2.4 3.0 3.4 
‘0 ——’ is tagged 
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‘1 --—' is tagged 
‘2 —-—' is tagged 


The next example shows a more complex set of tags and text strings. 


$m 
Example 15 
Script Example 
text .t —height 5 —width 65 —font {helvetica 12} 
grid .t 
t insert end \ 
"Text can have multiple tags at any given index.\n" Tl 


insert end \ 
"You can get a list of tags at an index with ’tag names’.\n" T2 


insert end \ 
"You can search the text with prevrange and nextrange.\n" 13 


insert end "You can get the ranges where a tag is \ 
defined with ’ranges’" T4 


it Set tags for 
## firstchar: first character on a line 


## firstline: first line on the text widget 

if secondline: second line on the text widget 

i## firstpage: all characters on this text widget 
.t tag add firstchar 1.0 

.t tag add firstline 1.0 {1.0 lineend} 

.t tag add firstpage 1.0 end 

.t tag add secondline 2.0 {2.0 lineend} 

.t tag add firstchar 2.0 

.t tag add firstchar 3.0 

.t tag add firstchar 4.0 


if Show some results 
ts "These tags are defined:\n [.t tag names ]\n" 

"These tags are defined at index 1.0:" 

" [.t tag names 1.0]\n" 

"Tag firstchar is defined for these ranges:" 

" [.t tag ranges firstchar]\n" 

"Tag T2 is defined for the range:\n [.t tag ranges T2]\n" 
"The first occurrence of firstchar after the" 

"start of line 3 is: 


D 
9) 
Dp 
9) 
9) 
D 
D 
Dp 


NnnNnnnnnn 
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puts " [.t tag nextrange firstchar 3.0]\n" 

puts "The first occurrence of firstchar before the" 
puts " start of line 3 is:" 

puts "  [.t tag prevrange firstchar 3.0]\n" 


Script Output 


These tags are defined: 
sel T1 T2 T3 T4 firstchar firstline firstpage secondline 


These tags are defined at index 1.0: 
T1 firstchar firstline firstpage 


Tag firstchar is defined for these ranges: 
1.0 1.1 2.0 2.1 3.0 3.1 4.0 4.1 


Tag T2 is defined for the range: 
2.0 3.0 


The first occurrence of firstchar after the 
start of line 3 is: 
i st a Se 


The first occurrence of firstchar before the 
start of line 3 is: 
2.0.2.1 


Text can have multiple tags at any given index. 
You can get a list of tags at an index with ‘tag names’. 


You can search the text with prevrange and nextrange. 
You can get the ranges where a tag is defined with 'ranges' 


Using Tags 

Tags are the interface into the text widget that allows you to bind actions to events on sections of text, 
set colors, set fonts, set margins, set line spacing, and so on. This section discusses a few of the things 
that can be done with tags and provides an example of how to use tags. The complete list of options 
you can set with a tag is in the on-line documentation. The tag bind command will bind an action to 
an event in a tagged area of text. 


Syntax: textName tag bind tagName ?eventType? ?script? 


textName The name of the text widget. 
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tag bind Bind an action to an event occurring on the tagged 
section of text, or return the script to be evaluated when 
an event occurs. 


tagName The name of the tag that defines the range of characters 
that will accept an event. 


?eventType? If the eventType field is set, this defines the event that 
will trigger this action. The event types are the same as 
those defined for canvas events in Section 11.5. 


script The script to evaluate when this event occurs. 


ooo 
Example 16 
Script Example 
it Create a text widget for example 
set textWidget [text .t —height 10 —width 60\ 
—font {helvetica 14}] 
grid $textWidget 


## insert some text 

$textWidget insert end "This is text with a " 
$textWidget insert end "secret" secretWord 
$textWidget insert end " in it" 


it Pop up a message box when someone clicks on the secret word 
$textWidget tag bind secretWord <Button—-1> \ 
{tk_messageBox —type ok —message "You found the secret! "} 


Script Output 


After clicking the word secret. 


This is text with a secret in it 


18, You found the secret! 


The tag configure command will modify how tagged text is displayed. The tag configure 
command will allow you to set many of the options that control a display, including the following. 


13.3 Text Widget Subcommands 473 


-foreground color The foreground color for the text. 

-background color The background color for the text. 

-font font ID The font to use when displaying this text. 

-justify style How to justify text with this tag. May be left, 
right, or center. 

-offset pixels The vertical offset in pixels for this line from the base 


location for displaying text. A positive value raises the 
text above where it would otherwise be displayed, and a 
negative value lowers the text. This can be used to 
display subscripts and superscripts. 


-Imarginl pixels The distance from the left and right edges to use as a 
-|Imargin2 pixels margin. The rmargin value is a distance from the right 
-rmargin pixels edge of the text widget to treat as a right margin. 


The Imarginl is a distance from the left edge to treat as 
a margin for display lines that have not wrapped, and 
Imargin2 is a distance to use as a margin for lines that 
have wrapped. 
-underline boolean Specifies whether or not to underline characters. 
The next example displays a few lines of text in several fonts and binds the creation of a label with 
more information to a button click on the word tag. 


eee 
Example 17 


Script Example 


i## Create and pack the text widge 
text .t —height 6 —width 70 —font {helvetica 12} 
grid .t 
if Insert some text with lots of tags 
.t insert end "T" {firstLetter} "he " {normal} 
.t insert end "tag" {code action} 
.t insert end " command allows you to create displays\n" {normal} 
.t insert end "with multiple fonts" {normal} "1" {superscript} 
.t insert end "\n\n" 
.t insert end "1" {superscript} 
.t insert end "Tcl/Tk: A Developer’s Guide, " {italic} \ 
"Clif Flynt, " {bold} 
.t insert end "Morgan Kaufmann, 2011" 
it Set the fonts for the various types of tagged text 
.t tag configure italic —font {times 14 italic} 
.t tag configure normal —font {times 14 roman} 
.t tag configure bold —font {times 14 bold} 
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## Set font and offset to make superscript text 
t tag configure superscript —font {times 10 roman} —offset 3 


it Set font for typewriter style font 
t tag configure code —font {courier 14 roman underline} 


i## Define a font to make a fancy first letter for a word 
t tag configure firstLetter —font {times 16 italic bold} 


if Bind an action to the text tagged as "action" 
t tag bind {action} <Button—l> { 

label .1 —text "See Chapter 13" -relief raised 
place .1 —x 50 -y 10 


Script Output 


The tag command allows you to create displays 
with multiple fonts! 


!Tcl/Tk: A Developer's Guide, Clif Flynt, Morgan Kaufmann, 2011 


After Clicking “Tag”: 


The t See Chapter 13|allows you to create displays 
with multiple fonts! 


'Tcl/Tk: A Developer's Guide, Clif Flynt, Morgan Kaufmann, 2011 


13.3.5 Inserting Images and Widgets into a text Widget 


Following the pattern used by the canvas widget, you can insert an image created with the image 
create command into a text widget with the textName image create command, and other Tk 
widgets can be inserted into a text widget with the textName window create command. 
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Syntax: textName image create index ?options? 


textName The name of the text widget this image will be placed in. 

image create Insert an image into a text widget. 

index The index at which to insert the image. 

?options? The options for the image create command include: 
-jimage handle The image object handle returned 


when the Tk image object was 
created. (See Section 10.8.) 


-name 7mageName A name to use to refer to this 
image. A default name will be 
returned if this option is not 
present. 


Fa $ $$ $$$ 
Example 18 
Script Example 
## Create a bird graphic 
set bird { 
RO1GODIhIAAGAJEAANNZ2QAAAP/////// yYH5BAEAAAAALAAAAAAGACAAAAKWhI+p 
yt+0Po5y02qtIHIJvFD8IPhrFDWAAxCPwjelD3N3dEfiYFB/zCD4mxcdMgo9H8TGT 
4ONRFARAGO9pFP8IPgYaxccjt+tJhI8Y1gx93dHcCUPgo+pSPGD4GMqUnyC j61J80k+ 
pibFJviYqhSb4GO0qR1BC+Ji6EZQQPqZqBCWE j6kbOfAxdSOIPqYuBI XwMXW5/WGU 
kz5SADS= 
} 


image create photo bird —data $bird 


if Create and pack the text widget 
text .t —height 2 —width 40 —background white —font {times 16 bold} 
pack .t 


.t image create 1.0 —image bird 
.t insert 1.1 " Watch the birdie" 


Script Output 
“fF Watch the birdie 


In the same fashion, another Tk widget (even another text widget) can be placed in a text widget 
with the window create object command. 
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Syntax: textNamewindow create index ?options? 


textName The name of the text widget that this window will be 
inserted into. 


window create Insert a Tk widget into the text widget. 


index The index at which to insert the Tk widget. 
?options? The options for the window create command 
include: 


-window widgetName The name given to this 
widget when it was created. 


-create script A script to evaluate to create 
the window if the - window 
option is not used. 


The text widget inserts the new image or widget at the requested index. It treats images and 
windows as if they were a single character. If the image or widget is inserted into an existing line, 
the height of the line will be increased to the size of the image. If you want to create a display with 
columnar format, you can use two text widgets and put the text for the left column in one text 
widget, and the text for the right column in the other, and then use window create to place the two 
text windows side by side. 


ae 
Example 19 
Script Example 


grid [text .t —width 60 —height 5 —background white] 
label .1 —text "label" 

.t window create 1.0 —window .1 

.t insert 1.1 " This is a label\n" 

.t window create 2.0 —create {button .bl —text "Button"} 
.t insert 2.1 " This is a button\ndescribed on two lines" 


Script Output 
label This is a label 


Button | This is a button 


described on two lines 


Notice in the previous example that described on two lines appears below the button, instead of 
having all text appear to the right. Images and windows appear on a line, just like text, and cannot span 
multiple lines. If you want to have an image that spans multiple lines, you must add a second text 
widget to hold the text, as shown in the next example. 

The -borderwidth and -highlightthickness options are used with the second text widget 
to make it “invisible.” By default, a text widget will have a border around it, which may not be the 
visual effect you wish. 
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Example 20 


Script Example 


set scroll 
RO1GODdhNQ 


IugED6m/g 


jomrFBsA40 
H8Um+P+Yu 
fRSb4GPqch 
UXyCj6nLbR 
RvEJPqYut 
6nIDxQ+Cjo6 
+Ji63EDXje 
CD6mLjPFP4 
+Ji6zBQFCT 
Y+pyU3wjtJ 
qctN8Y3gY+ 
pi43UPwg+d 
/CD4mLrcQP 
bRSf4GPqch 
UWyCj6nLfR 
sQk+pi73U 
Tf i YumwUh+ 
AnBj8G 


X1ASAKD4BD 
+BT/CD4mL 
YCiOZECUAD 
} 
image 
grid 


[text 


C 


U 


4 


/ 
S 


6 


G 
V 
S 


B 
A 


S 


{ 


txHsSQk+pi73U 


H8IPiY 


BjondTfCP4 
PqctN8Y3gY+pyU 
Li/FR4KPqctL8 
163BT/CD6 
pyA8U3go+ j 
163EDxjeBjondTf 
4GPqchvFJ/iY 
FJ/iYutxG8Qk4 
4GPqch/FuviY 
yCj6onLjRs 
DRAQi 10QQQi S- 


D 


D 


EVEhfEZdCOOAEBFBOQCI 


AJEAAP///wAAAP///////ywAAAAANQC1AAAC/4S 
BjorJRfEwj+Ji6S/GD4FNsgo+pqxSf4B/F 


$968+z8RsQk+pi43xccgtJi6jBOfke 
JviYukmxAQAOCEBEBMHH1IM2gJABA8QEAjuBj6i 


AYgIICQRAAAUEz6m7/ gUIAYgAIC 


Y+piUBKAiCD4FxGIiAghROIAXBB8i IHARTQQQi QOAFWAAaDY BBY 


PqbuUmyCT7EJPqY uA8Umt+di 63E 


J/iY 


WyCJ6nL#RS#4GPqch 
txG80k+pi63UXyCj6nLbR 


4GPqchvFJ/iYutxG8YPgY+pyA8 


DRQ/CD6 


BB9TF4MSwre 


txA8YPgY+ 
LjdQ/CD 
LrcoFN//CD6mLjfFN4 
/wj+di6zBT/CD6mLjPFP4KPqct 


py03x 


H 


tpi7 
tx 


H4GPqciP 


tEey 


KA 


lighfEzdCOoAEBFAS 
iguBj615QEgCACArhU2yCj6mLQ 


8TGD4GPqs1F8RIK 


Bi 
D 


pyA8UPgo+pywOUPwg+tpi 


4mLrcQPGN4G 


gY+oyU/wjtd 
PqctM8Y/gY 


sf 
Li 
4mLrcQPGD4G 
G8YPgY+pyA8 
3UXyCjo6nLbR 
H8Qk+pi63UX 
FJviYutxHsQ 
ICI KPqbsUHw 
BB9OT9AKSAA 

C 

U 


PqctJ8ZHgY+ 


LFBrgzICARQfA 
RBsCOC4GPqX1A 


hxCDomLjdSH 
vFJ/iYutxHsQ 
Sf4GPqch/Fuvi 
UPgo+py20Un+B 
43UHw 
PqacIN8I/iYutw 
PqctN8Y3gY+p 


16zBT/CD6mLjP 
pyU3wj+Ji63BT 
rcFN8IPqYuN8U 
PqacgPFD4KP/6n 
UPgo+pywOUPwg 
Sf4GPqchvFJ/i 
fRSb4GP 
+pi73UWyCj6n 
EAMAg+pm5SbAC 
BEEJwwiAgk4wP 
TAICgJwefUvaA 
IPgLFJviYukm 


pyA8Um+d 1 63P4 


create photo scroll —data $scrol] 


PqcvtD60ctNqL 
xdS80CUBEBAGJ 
SiAgAQkKKwI4Lg 
TN40SAABOQFAYC 
PqcuNFuvgY+py 
+pi73UWyCj6nL 
YutxH8Qk+pi 
j6nIbxSf4 
j+Ji63EDxgt+Bj 
U3wg+pi43UPwg 
yU/wjt+Jdi6zBT/ 
8Y/gY+oyU/wj 
FPAKPqctM8Y/g 
fFCD6mLjfFN4KP 
3got+pywOUPwg+ 
LDRQ/CD6mLjdQ 
+pi63UXyCj6nl 
YutxG8Qk+pi73 
qch/FJviYutxH 
LfRSb4GPqciPF 
4AATQEUHWMXUx 
qX1ACAIgIghNh 
EABTfAACQ4GPq 
xCf5RFIKPqasu 
wykmrvTjrzbv/ 


.t —width 65 —height 12 —background white] 


.t image create 1.0 —image scroll 


text 


.t2 —width 35 —height 5 —background white \ 


—font {times 16 bold} —borderwidth 0 \ 
—highlightthickness 0 


.t window create 1.1 —window 


et2 
2 
Jbe 
«be 
.t2 


insert 
insert 
insert 
insert 
insert 


oF wWMnrm Fr 


Co <P a eS eS 


"And we’ 1] 


22 


"When laying out pictures and text\n 
"You may begin feeling quite vexed\n 
"Put a window in line\n" 

"And the layout works fine\n" 

render HTML next." 
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When laying out pictures and text 


You may begin feeling quite vexed 


Put a window in line 
And the layout works fine 
And we'll render HTML next. 


/ HTML DISPLAY PACKAGE 


HTML is currently the most portable protocol for distributing formatted text and the odds are good that 
HTML will continue to be important for many years. The text widget tags make it possible to use the 
text widget to display HTML text with little work. 

Stephen Uhler wrote html_library, a library that will display HTML in a text widget. The 
html_library is a good example of what you can do with the text widget, so we will examine it. 
The HTML library is not a part of the standard Tk distribution. It is available on the companion website 
and on the web at the following address, among other locations. 


e = http://oucorp.com/ 


The htm117b parsing engine is used in the tc11ib (http://cllib.sfnet/) htm1 parse package. 

There is also an HTML display widget that is written in C. The C Language HTML widget is much 
faster at rendering pages, but the Tcl widget is easier to merge into applications for simple displays like 
HTML formatted documentation and embedded help pages. 


13.4.1 Displaying HTML Text 
Using the htm1_library package to display text is very simple, as follows. 


Step Example 
1. Source the html_library code. source htmllib.tcl 
2. Create a text widget to contain the text .t 
displayed HTML text. 
3. Map the text widget to the display. pack .t 
4. Initialize the HTML library by calling HMinit_win .t 
HMinit_win. 


5. Display your HTML text by calling HMparse_-html HTML_TEXT "HMrender .t" 
HMparse_html. 


The following example shows a text window being used to display some HTML text and a dump 
of the first couple of lines. Note that the tags are used to define the indenting and fonts. 
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eee 
Example 21 


Script Example 


i## Load the htmllib scripts 
source “htmllib.tcl" 


i## Create and display a text widget 
grid [text .t —height 10 —width 50] 


df Initialize the text widget 
HMinit_win .t 


if Define some HTML text 

set txt { 

<HTML><BODY>Test HTML 
<P><B>Bold Text</B> 
<P><I>Italics</I> 

</BODY</HTML> 

} 


if and render it into the text widget 
HMparse_html $txt "HMrender .t" 


if Examine what’s in the text widget 
set textDump [.t dump —all 1.0 4.0] 
puts "[Lformat "%—-7s %-30s %6s\n" ID DATA INDEX]" 
foreach {id data index} $textDump { 
puts "[format {%-7s %-30s %6s} $id [string trim $data] $index]" 


Test HTML 


Bold Text 


Italics 


ID DATA INDEX 


mark current 1.0 
tagon 1.0 
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tagon indent0 1.0 
tagon font:times:14:medium:r 1.0 
text Test HTML 1.0 
tagoff indent0O 1.71 
tagoff 1.11 
tagon space 1.11 
text Oe ts 
text 2.0 
tagoff space 3.0 


You can see that the htm] library uses tags to define the fonts for the text widget to use to display 
the text. 


13.4.2 Using htm1_library Callbacks: Loading Images and Hypertext Links 


To display an image, the html_1ibrary needs an image widget handle. If the library tried to create 
the image, it would need code to handle all methods of obtaining image data, and the odds are good 
that the technique you need for your application would not be supported. 

To get around this problem, the htm]_l i brary calls a procedure that you supply (HMset_image) to 
get an image handle. This technique makes the library versatile. Your script can use whatever method 
is necessary to acquire the image data: load it from the Web, extract it from a database, code it into the 
script, and so on. 

The requirements for handling hypertext links are similar. A browser will download a hypertext 
link from a remote site, a hypertext on-line help will load help files, and a hypertext GUI to a database 
engine might generate SQL queries. When a user clicks on a hypertext link, the htm] _1 i brary invokes 
the user-supplied procedure HM] ink_cal1back to process the request. 

Note that you must source html_library.tcl before you define your callback procedures. 
There are dummy versions of HMset_image and HMlink_callback in the html_library pack- 
age that will override your functions if your script defines these procedures before it sources the 
html_library.tcl script. 

One of the requirements of event-driven GUI programming is that procedures must return quickly. 
When the script is evaluating a procedure, it is not evaluating the event loop to see if the user has 
clicked a button (perhaps the Cancel button!). In particular, if the procedure acquiring image data is 
waiting for data to be read from a remote site, you cannot even use update to force the event loop 
to run. Therefore, the htm]_1ibrary package was designed to allow the script retrieving an image to 
return immediately and to use another procedure in the htm1_library to display the image when it is 
ready. 

The following flowchart shows control flow when the htm1_]1ibrary code encounters an <IMG> 
tag. Note that the creation of the image need not be connected to the flow that initiated the image 
creation (the HMset_image procedure). An outside event, such as a socket being closed, can invoke 
HMgot_image. 
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htmllib library application script 


HMParse reads text and invokes HMrender 
to process HTML tags 


HMrender encounters and <IMG> tag 
HMrender invokes HMtag_img 
HMset_image starts to acquire the image. 


HMset_image may wait for the image to 


2 z : = be created or may schedule a procedure 
HMtag_img creates an identifier for this image to be evaluated when the image is created. 
HMtag Invokes HMset_Image 


( HMtag_image returns to HMrender \—| HMset_image returns to HMtag_image } 
HMrender returns to HMparse 

HMparse continues processing the text ATk image has been created 
HMgot_image places the image in the HMgot_image is invoked with the identifier 
appropriate location of the text widget for this image and the image handle 


When HMset_image is called, it is passed a handle that identifies this image to the htm]l_library. 
When the application script calls HMgot_image, it includes this handle and the image object handle of 
the new image object so that the htm1_1i brary code knows which <IMG> tag is associated with this 
image object. 


Syntax: HMset_image win handle src 


Create an image widget from the appropriate data, and transfer that 

image widget back to the htm]_library by calling HMgot_image. 

win The name of the text widget that will ultimately receive the 
image. 

handle A handle provided by the htm1_library script that must be 


included with the image handle when HMgot_image is 
invoked. 


Src The textual description of the image source. This is the content 
of the SRC="XXX" field. 
Syntax: HMgot_image handle image 


Maps an image widget handle into a text widget in the location 
defined by data associated with hand/e. 


handle The value that was passed to HMset_image as an argument. 
image The image handle returned by an image create command. 
The next example displays the Tcl feather logo. In this example, the HMset_image call is done as a 


hard-coded image creation. In an actual application, this would be code to parse the src parameter, 
and so on. 
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7——__A_ 
Example 22 
Script Example 
source htmllib.tcl 
set logo { 
RO1GODdhKwBAAKUAAP////r6+vX19e3t7fPz8+j 060bm5uDg4NXVlaurq56e 
nnVidcjlyOLi4ufn/5T090vr6+zs70Hh4Xt7eldSUSXFxX9/f2FhHYeTK5I+P 
j3dycn19fbWItUVFRWtradmZmY 2Njd/f38LCwvHx8ZycnPf39wAAAAAAAAAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACWAAAAAKWBAAAAG/ KCACEGSEQOC 
pGAgMDqLyCRhQCOYDtgDISFNKL7fxKH5NAG84LR6ZU4UINNGIZtk2+94tiCA 
zvv/CgkAf ICFelIAfXYLYAuMhmo I QopsDGAN! pBpB5N4AwyODg8NmpudbAsM 
Awqpq6VpBkITiwONjJ+PjayFBUIHiwygDA65uxBLhQO0+wKw0ol0JexERCMV3 
ygC/eQ5pCwkBEhMUFBWAZNrAxF/eAhLj4xbmy3cLzrkD7u8XgN9CBtuNMBh4 
hc 
K 
I 


Ny5DGnsKukKVBBKAAQDADXL3TSCHNAGLInoUZ4hC PwgUH803bFwjisOxgJAlx 
dSfTggISC2YoEODArTucVubRi IHg/rgJEy IMSKWOTU4ALPMK40BzXIcCAzxg 
sgYmls4/CT40pXBBgM2i bHoJECBPalMQZxRoZ AFmsZn2GGIrSTtu3f8x+ 
iFlglh8ybv8wusCVg80PBqjqGYL3kALCFkKK8qO0DJTj8hhPJQIVxBMtddfhg0O 
qqxmAYEIWjsX3IKICGkK1IA7R20CBi 5Thqf1Q0ed2o0gNYLvn804G1qSGZ6wY Gb 
nNUAAKO7ReERZAY Kp83lehrRn/7WYCBqQWY4zhgDO2k8STEkilEHFcBgulloslb 
Trt+teAgn3WANoD12BgngqJFdiU335+HDDBf+0g8wdgSdGTwAQXx0ZfAwrmwaBg 
CnxQ3Uzj/vO1RIOWPVY dBRMU8N4aBHy43RgfPFUDBR8I+EdbINolwVP5hJDA 
i DBXJINGBWjXgTomGtNxXRHwZWMNAHUAE: FgD/FFKBkvZVxMsSQF foxUzyQWJUN 
ACU8EU7 U0SBX1FZ3gEAK2SGOY d8Y KAJhi B9eNHHmgo!l 8Qi1eX7zZFZ5xYgjEI 
nOKkseYCeuZZaJ95VqabX4EEAMZbY o65kaBp1NHGEJAKgqkahKkKkxppl kwcmQ 
xWeqcXikKIhppl4tjnnboamWukxXt5bgaq64wkf rKS5BcRhywdpAxLLFrNHEc 
sgtCx6w8cLZxrB/K4NUFFgZAxcQeUSghQBXUDFDAUAZcCkKYUWDQgoSOAS+pXh 
7rtOBAEAOw==\\ 


set HTMLtxt { 
<HTML> 
<HEAD><TITLE>Example of Embedded image</TITLE></HEAD> 
<BODY> 
<B>Tcl</B> 
<IMG src=logo> 
<B>Powered</B> 
</BODY> 
</HTML> 


} 

HAHAHA AAR AAA AAA AAA AAA AAA AE 

d## proc HMset_image {win handle src {speed {0}}}—\ 
i## Acquire image data, create a Tcl image object, 
if and return the image handle. 


dt 
if Arguments 
if win The text window in which the html is rendered. 


if handle A handle to return to the html library with 
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if the image handle 

# src The description of the image from: 

dt <IMG src=XX> 

dF 

## Results 

i## This example creates a hard-coded image. and then invokes 
i## HMgot_image with the handle for that image. 


proc HMset_image {win handle src {speed {O}}} { 
global logo 
puts "HMset_image was invoked with WIN: \ 

win HANDLE: $handle SRC: $src" 

# In a real application this would parse the src, and load the 

it appropriate image data. 

set img [image create photo —data $logo] 

HMgot_image $handle $img 

return "" 


} 
text .t —height 6 —width 50 
pack .t 
HMinit_win .t 

HMparse_html $HTMLtxt "HMrender .t" 


Script Output 


HMset_image was invoked with WIN: .t HANDLE: .t.9 SRC: logo 


Ve 


Tel | f, Powered 


The html_library uses a technique similar to the image callback procedures to resolve hyper- 
text links. When a user clicks on a hypertext link, the parsing engine invokes a procedure named 
HM1ink_cal1lback with the name of the text window and the content of the href=value field. The 
html_library provides a dummy HM1ink_cal1back that does nothing. An application must provide 
its own HM1ink_callback procedure to resolve hypertext links. 


Syntax: HMlink_callback win href 
A procedure that is called from the htm1_library package when a 
user clicks on an <A href=value> field. 


win The text widget in which the new text can be rendered. 


href The hypertext reference. 
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The next example shows an HM1 ink_cal]back that will display the HTML text contained in a Tcl 
variable. In a browser application, the HM] ink_callback procedure would download the requested 
URL, and in a help application it would load the requested help file. 


————————— ee eee eee 
Example 23 
Script Example 


source htmllib.tcl 


/HAHABAB AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AE 
d## proc HMlink_callback {win href}—— 

i## This procedure is invoked when a user selects a hypertext 
## link in the HTML display 


if In an actual browser, the href field would contain the URL of 
i## the HTML page to retrieve. In this example, it contains the 
if name of a Tcl variable 


fl 

if Argument 

d## win The window in which the new page will be displayed 
i## href The hypertext reference 

i 


proc HMlink_callback {win href} { 
global HTMLText2 HTMLText HTMLText3 
puts "HMlink_callback was invoked with win: $win href: $href" 


if Clear the window 
HMreset_win $win 


## Display new text 
i## — href will be substituted to the name of a text string, 
if and "set varName" returns the contents of a variable. 
if "[set $href]" could also be written as "[subst $$href]" 
HMparse_html [set $href] "HMrender $win" 
} 


i## Define three sets of simple HTML text to display 
i## This is the first text to display. It is an Unordered List of 
i## hypertext links to the other two sets of HTML text. 
set HTMLTextl { 
<HTML> 
<HEAD><TITLE> Initial Text </TITLE></HEAD> 
<BODY> 
<UL> 
<LI> 
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<A href=HTMLText2> Clicking this line will select text 2.</A> 
<LI> 
<A href=HTMLText3> Clicking this line will select text 3.</A> 
</UL> 
</BODY> </HTML> 
} 


i## This text will be displayed if the user selects the 
## top line in the list 
set HIMLText2 { 
<HTML> 
<HEAD><TITLE> Initial Text </TITLE></HEAD> 
<BODY> 
<CENTER>This is text 2.</CENTER> 
</BODY> </HTML> 
} 


## This text will be displayed if the user selects the 
# bottom line in the list 
set HIMLText3 { 
<HTML> 
<HEAD><TITLE> Initial Text </TITLE></HEAD> 
<BODY> 
<CENTER>This is text 3.</CENTER> 
</BODY> </HTML> 


# Create the text window for this display 
text .t —height 6 —width 60 —background white 
grid .t 


# Initialize the html_library package and display the text. 


HMinit_win .t 
HMparse_html $HTMLTextl "HMrender .t" 


Script Output 


HMlink_callback was invoked with win: .t href: HTMLText2 


Before clicking the hypertext link 


Clicking this line will select text 2. 


Clicking this line will select text 3. 
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After clicking the top line 


This is text 2. 


13.4.3 Interactive Help with the text Widget and html1lib 

The next example shows how you can use the text widget bind command, an associative array, and 
the htm] library to create a text window in which a user can click on a word to get help. The tag 
bind command causes a mouse click event to invoke the ShowHe!p procedure. 


$ textWin tag bind help <Button-1>\ 
Llist textWithHelp::ShowHelp $textWin %x ay] 


When someone clicks on the text widget, the text widget invokes the textWith- 
Help::ShowHelp procedure with the name of the text widget and the X and Y cursor location. 
Within the ShowHelp procedure, the format converts the X and Y position to a text widget index. 


if Convert the X and Y cursor location into a text index. 
set index [format "@%d,%d" $x $y] 


That index is used to identify the start and end locations of the word that was clicked, and to get 
that word from the text widget with the following code. 


## Get the word that surrounds that location from the text widget 
set word [$txt get [list $index wordstart] Llist $index wordend]] 


By default, the text widget allows a user to edit the text with common emacs bindings or arrow 
keys. The last line: 


$ txtWin configure -state disabled 


disables the editing, making the window read-only. This is appropriate for a display you do not want a 
user to modify. 

In the following example, only the word text has help associated with it, and all words in the 
text widget are tagged with the string he! p. For other applications, you might adda tag configure 
command to the textWithHelp to make words with help highlighted, and only tag the words that are 
in the index. 


$$ 
Example 24 
Script Example 

HiMMMa fg GtiititiiMiiicannainaia 

i## proc textWithHelp {args}—— 

i## Creates a text widget with a binding for context 

if sensitive pop—up help 

if Arguments 
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if args A list of arguments appropriate for the 

if text widget 

# 

i## Results 

i## Creates a new text widget with a binding on the tag *help’ 
if Returns the name of the new widget 


proc textWithHelp {args} { 
set textWin [eval text $args] 
$textWin tag bind help <Button-l> \ 
[list textWithHelp::ShowHelp $textWin %x Z%y] 
return $textWin 


} 


namespace eval textWithHelp { 
variable helpDocs 


HMMM MMM aae 
## proc addHelp {key text}-— 

i## =Add help text to the help database. 

if Arguments 

if okey The keyword to identify this help message 

if text An HTML text message. 

## Results 

## Updates the helpDocs array. 


proc addHelp {key text} { 
variable helpDocs 
set helpDocs($key) $text 
} 


HMMM iM Raae 

i## proc ShowHelp {txt x y}-— 

i## }=3©9Finds the word with the cursor and checks that this 

## = =word is an index into the helpDocs array. If so, it 

i## =3©ocreates a popup window with a text widget, scrollbar, 
# = anda *Done’ button. The text widget will display the 
i## }==HTML formatted text indexed by the keyword. 


dF 

if Arguments 

# txt The name of the parent window. 

it 6x Cursor X location 

# oy Cursor Y location 

## Results 

i## ~=Any previous popup help window associated with this text 
if widget is destroyed 


i If the cursor is on a word with help, a new toplevel 
if widget is created with the help text. 
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proc ShowHelp {txt x y} { 
variable helpDocs 


if Convert the X and Y cursor location into a text index. 


set 


# Get 
text widget 

t word [$txt get [list $index wordstart] \ 
[list $index wordend] ] 


# 


$e 


iF 
if 


} 
} 
} 


iF 


f 
{[ 


index [format "@%4d,%d" $x $y] 


the word that surrounds that location from the 


the word exists, do stuff, else just return. 
info exists helpDocs($word)]} { 


## Destroy any existing window. 


Ca 


tch {destroy $txt.help} 


## Create a new toplevel, and title it appropriately 


se 
wm 


t help [toplevel $txt.help] 
title $help "Help for $word" 


i## Create a new text widget, scrollbar and exit button 
text $help.t —width 60 —height 10 \ 


—yscrollcommand "$help.sb set" 


scrollbar $help.sb —orient vertical \ 


bu 


—command “$help.t yview 
tton $help.b —text "Done" —command "destroy $help" 


## Map the widgets to the toplevel window 


gr 
gr 
gr 


# 
# 


id $help.t —row 1 —column 
id $help.sb —row 1 —column 2 —sticky ns 
id $help.b —row 2 —column 


nitialize the text widget for HTML and render the 
text 


HMinit.win $help.t 
HMparse_html $helpDocs($word) "HMrender $help.t" 


i## A sample use of the previous code 


iF 


i## Load the html display library 
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source htmllib.tcl 


it Add a help message to the help index. 
textWithHelp::addHelp text \ 
{<BODY> 
<CENTER><H4><CODE>text</CODE> widget</H4></CENTER> 
<CODE><B>Syntax: </B>text <I>textName ?options?</I></CODE> 
<P> 
The text widget can be used to display and edit text. 
</BODY> 
} 


## Create and map the text window 

set txtWin [textWithHelp .txt —background white —height 5 \ 
—width 60 —font {arial 16} ] 

grid $txtWin 


if Insert text into the text widget. 
$txtWin insert end \ 
"The text widget is part of the standard Tk toolkit." help 


if Make the text window read only — disable editing. 
$txtWin configure —state disabled 


Script Output 


Before clicking on the word text 


The text widget is part of the standard Tk toolkit. 


After clicking on the word text 


The text widget is part of the standard Tk toolkit. 


Help for text 


text widget 
Syntax: text textName ?options? 


The text widget can be used to display and edit text. 


Done 
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The previous example has hard-coded text to make an example that can be placed in the book. 
Your applications may use the http package to download pages from a remote site, load pages 
from a disk, generate pages from database records, or whatever technique your program specifications 
require. 

The ease with which HTML support is added to the text widget may make you think that it would 
be easy to write a full browser with Tk. Before you do too much work on that project, take a look at 
Steve Ball’s plume browser at http://ftp.sunet.se/pub/lang/tcl/sorted/apps/plume-6.2/ and read Mike 
Doyle and Hattie Schroeder’s book Web Applications in Tcl/Tk. Much of the work you will need to do 
to create a browser has already been done. Using a text widget to implement a browser display has the 
following problems. 


e Performance: Displaying HTML in a text widget requires a great deal of parsing HTML and 
calculating layout parameters. This can be compute intensive, and becomes slow when done in an 
interpreted language like Tcl. 

¢ Layout limitations: The text widget is optimized for pure text displays. As discussed in 
Section 13.3.5, you need to add extra windows to flow text around images, and so on. 


D. Richard Hipp solved these problems with his TKHTML widget 
(www.hwaci.con/sw/tkhtml/index.html). This widget is the basis for several applications, including the 
full-featured BrowseX web browser (hitp://browsex.com/). 

The htmllib.tcl package is useful as a lightweight, portable, and easily configured HTML 
display widget for applications like application help, runtime documentation, etc. 


13.5 BOTTOM LINE 


e The text widget will display formatted text. 
e By default, the text widget allows the user to edit text. 
e The text widget supports: 
e Multiple fonts 
e Multiple colors for foreground and background 
e Varying margins 
e Varying line spacing 
e Binding actions to characters or strings 
e Including images and other Tk widgets in text 
e Locations in the text widget are identified as line and character positions. Only locations where 
text exists can be accessed. 
e Lines that are longer than the display can wrap. If this occurs, the line and character index points 
reflect the internal representation of the data, not the display. 
e A text widget is created with the text command. 
Syntax: text textName ?options? 
e Text is inserted into a text widget with the insert subcommand. 


Syntax: textName insert index text ?taglList? ?moreText? ?moreTags? ?...? 
An image is inserted into a text widget with the > textName image create subcommand. 
Syntax: textName image create index ?options? 

A Tk widget can be inserted into a text widget with the textName window create subcom- 
mand. 

Syntax: textNamewindow create index ?options? 

Text is deleted from a text widget with the del ete subcommand. 

Syntax: textName delete startIndex ?endIndex? 

You can search for patterns in a text widget with the search subcommand. 

Syntax: textName search ?options? pattern startIndex ?endIndex? 

A mark is placed with the mark set subcommand. 

Syntax: textNamemark set markName index 

A mark is removed with the mark unset subcommand. 

Syntax: textNamemark unset markName ?...? ?markNameN? 

You can get a list of marks with the mark names subcommand. 

Syntax: textName mar ames 

You can iterate through the marks in a text widget with the mark next and mark previous 
subcommands. 
Syntax: textName mar ext index 

Syntax: textNamemark previous index 

You can add tags either in the insert subcommand or with the tag add subcommand. 


Syntax: textNametag add tagName startIndexl ?endl? ?start2? ... ?endN? 
You can remove a tag from a location with the tag remove subcommand. 

Syntax: textNametag remove tagName startIndexl ?endl? ?start2? ... ?endN? 
You can remove all references to a tag with the tag delete subcommand. 

Syntax: textNametag delete tagName ?tagname2? ... ?tagNameN? 


You can get a list of tag names with the tag names subcommand. 

Syntax: textName tag names index 

You can iterate through tag locations with the tag nextrange and tag prevrange subcom- 
mands. 
Syntax: textName tag nextrange tagName startIndex ?endIndex? 

Syntax: textNametag prevrange tagName startIndex ?endIndex? 

You can bind an event to an action that occurs on a character or string with the tag bind 
subcommand. 
Syntax: textNametag bind tagName ?eventType? ?script? 

The html1ib.tcl library provides a set of procedures that will render HTML into a text widget. 
Images are inserted into the HTML document with the HMset_image and associated HMgot_image 
procedures. 
Syntax: HMset_image win handle src 

Syntax: HMgot_image handle image 

Hypertext links are inserted with a user-supplied HM] ink_cal1lback procedure. 
Syntax: HMlink_-callback win href 
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13.6 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range ___ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a |-5 line script. These problems should each take under a 
minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 


800-399 Long exercises may require reading other material or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e 100 What is the top line in a text widget? 

e 10] What index string would match the start of a word that includes the index 2.22? 

e 102 What units are used to define the height and width of a text widget? 

e 103 What command will return a list of all marks in a text widget? 

e 104 Can a mark exist in multiple locations in a text widget? 

e 105 Can a tag exist in multiple locations in a text widget? 

e 106 What command would display characters tagged bold using the font {times 16 bold}? 
e 107 What Tcl script library can be loaded to render HTML data? 


e 108 What command would cause the procedure highlightText to be invoked when a user 
clicks on a word in the text widget .t? 


e 109 What marks are always present in a text widget? 
e 110 What tags are always present in a text widget? 
e 200 Create a text widget and insert the text words Hello, World into the widget. 


e 201] Create a text widget and vertical scrollbar. Add 100 lines of text into the text widget and 
confirm that the scrollbar will display them all. 


e 202 Write a procedure proc insertText {txtWin text} that will accept the name of a text 
widget and a string of text. The procedure should tag the first character of each sentence as “red”, 
and insert the text into the text widget. Use tag configure to make the first letter of each 
sentence appear red. 


e 203 Write a procedure that will report all tags that overlap some section of text. 
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204 Write a script using the text widget (not canvas) that shows an image in the center of the 
text widget, and text surrounding the image. There should be multiple characters displayed on 
each side of the image, and multiple lines above and below the image. 


205 Write a procedure proc highlightText {textName string} that will search a text 
widget for all occurrences of string and highlight those occurrences. 


300 Write a set of scripts with a label and text widget. The label should display the word 
currently under the mouse cursor as the mouse is moved about a text widget. 


301 Write a procedure that will accept the name of a text widget as an argument and modify the 
text in that widget to show what areas are tagged, and what the tag is. This may require adding line 
feeds to the text to create blank lines to hold annotation. 


302 Expand the example in section 13.4.3 by adding a procedure insertText helpTextName 
text that will check each word in the text string and underline all words for which help has been 
added. 


303 Write an editor with a text widget, and a File menu that includes Load and Save options. 
The load and save commands can be implemented with a toplevel widget that contains an entry 
widget for the file name and a Done and Cancel button. 


304 Write a multiple-choice test program that displays a set of questions, via a set of radio 
button widgets, for the user to select the answer. 


CHAPTER 


Tk Megawidgets 


The widgets described in Chapter 11 are relatively small and simple objects created to serve a single 
purpose. They are designed to be combined into larger and more complex user interfaces in your 
application. 

Many applications require more complex widgets. A program that allows a user to save or read data 
from a disk file will need a file selection widget that supports browsing. Many applications require a 
listbox or text widget that displays a scrollbar when the number of lines displayed exceeds the 
widget height. 

Tk supports merging several widgets into a larger widget that can be reused in other applications. 
These compound widget interfaces are commonly called megawidgets. 

The standard distribution of the Tk toolkit contains a few megawidgets, and many more 
megawidgets are supported in Tk extensions and packages, including iwidgets (<http:// 
sourceforge.net/projects/incrtcl/>), and Bwidgets (<http://sourceforge.net/ 
projects/tcllib/>). 

Megawidget packages can be created using only Tk or with C language extensions to wish. 
This chapter will discuss the megawidgets included with the standard distribution and techniques for 
building script-level megawidget libraries using namespaces or TclOO. 


14.1 STANDARD DIALOG WIDGETS 


The standard distribution provides several megawidgets to simplify writing applications. These 
widgets extend the functionality of the Tk interpreter and save the script writer from having to reinvent 
some wheels. 

The implementation of these widgets varies among the platforms Tcl supports. On the UNIX 
platform, they are all implemented as .tcl scripts in the TK_LIBRARY directory. The Windows 
and Macintosh platforms already support some of these widgets, in which case Tk uses the native 
implementation. 

If you prefer to have your application use the Motif-style widgets instead of the native widgets 
(perhaps it is important to have the application appear the same across multiple platforms, rather 
than adhere to the platform look and feel), you can force the Motif look and feel by performing the 
following. 
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—_ 


. Set the global variable tk_strictMotif to 1. 
2. Delete the compound widget commands you wish to have appear as Motif. 
3. Source tk.tcl. 


A code snippet to change the color selector will resemble the following. 


set tk_strictMotif 1 
rename tk_chooseColor 
source [file join $tk_library tk.tcl] 


14.1.1 tk_optionMenu 


This menubutton widget displays the text of the selected item on the button. The widget creation 
command returns the name of the menu associated with the button name provided by the script. 


Syntax: tk_optionMenu buttonName varName vall ?val2...valN? 

Create a menu from which to select an item. 

buttonName A name for the button to be created. This name must not belong to an 
existing widget. Once the tk_optionMenu call has returned, this 
name can be used to display the widget. 

varName The text variable to be associated with the menu. The selected value 
will be saved in this variable. 

val* The values a user can select from on this menu. These values will 
become the elements in the menu, and the selected value will be 
displayed on the button face. 


Example 1 

Script Example 
tk_optionMenu .button varName Vall Val2 Val3 
grid .button 


Script Output 


After selection 


optionMenu 


= —_— | 
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14.1.2 tk_chooseColor 

This color selector widget returns a properly formatted string that can be used for a color name. The 
string is the red-blue-green value displayed in the Selection field. This command creates a new window 
in the center of the screen and disables the other windows in the task that invoked it until interaction 
with this widget is complete. 


Syntax: tk_chooseColor 


Example 2 
Script Example 


set newColor [tk_chooseColor] 


Script Output 


W217 Selection: 
Red: I 


#d9d9d9 


a 
Green: 217 
a 
e217 
a 


Custom colors: 


S456 Huefs2 Red: [106 
Satj13? Green: |215 
bee cineca] CaewSat Liens | Bue 2 


Cancel | Add to Custom Colors | 
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Canes) OED 
4 


14.1.3 tk_getOpenFile 


This file browser widget returns the name of a file that already exists. If the user types in a 
nonexistent file name, an error message dialog box is displayed, and the window focus is returned 
to the tk_getOpenFi le window. This command creates a new window on the screen and disables the 
other widgets in the task that invoked it until interaction with this widget is complete. 
Syntax: tk_getOpenFile ?option value? 
Create a file-browsing widget to find an existing file. 
?option value? 
The options supported by the tk_getOpenFi le megawidget include: 
-defaultextension ext The extension string will be appended to a file 
name entered by users if they do not provide an 
extension. The default is an empty string. This option 
is ignored on the Macintosh. 
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-filetypes patternList This list is used to create menu entries in the Files of 
type: menubutton. If file types are not supported by 
the platform evaluating the script, this option is 
ignored. 


-initialdir path The initial directory for the directory choice 
menubutton. Note that on the Macintosh the General 
Controls panel may be set to override application 
defaults, which will cause this option to be ignored. 

-initialfile fileName Specifies a default file name to appear in the selection 
window. 

-parent windowName Specifies the parent window for this widget. The 
widget will attempt to be placed over its parent but 
may be placed elsewhere by the window manager. 

-title titleString The title for this window. The window may be 
displayed without a title bar by some window 
managers. 


2? i@@#$#_ 


Example 3 
Script Example 
set typeList 
{ {Include Files} {.h} } 
{ {Object Files} {.o} } 
{ {Source Files} {.c} } 
{ {. } 


{All Files} 
} 
tk_getOpenFile -initialdir . -filetypes $typeList 


Script Output 


Directory:  /usr/local/lib/tk8.6 


| choosedir.tcl [| focus.tel 
| clrpick.tel |_| fontchooser.tcl 
| comdlg.tcl || iconlist.tel 
=] console.tel =| icons.tel 
[| bgerror.tcl [| dialog.tcl [| listbox.tel 
[-| button.tel —| entry.tel [| megawidget.tcl 


[al 


File name: Open | 


Files of type: All Files (*.*) Cancel 
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Look in: System32 


= Name Date modified Type i = 
ay 0409 7/13/2009 10:37 PM File fol — 
Recent Places) advancedinstallers 7/13/2009 8:20PM File fol 
= Dar-sa 7/13/2009 8:20PM File fol 
}) bg-BG 7/13/2009 8:20PM File fol 
Desktop )) Boot 7/13/2009 10:37 PM_— File fol 
Di catroot 7/13/2009 10:10 PM_— File fol 
| ry catroot2 7/13/2009 10:10 PM_— File fol 
Libraries }) Codeintegrity 11/10/2011 1:38 AM File fol 
com 7/13/2009 10:37 PM File fol 
a Li config 11/10/20111:40 AM File fol 
Computer i cs-CZ 7/13/2009 8:20PM File fol 
) da-DK 7/13/2009 8:20PM File fol 
de-DE 7/13/2009 8:20PM __File fol fe 
4 


File name: 


Files of type: 


Q 


_| msgcat-1.4.3.tm 
_} teltest-2.3.2.tm 


) LotsaData 
|) Something 2 


E idisk 


PLACES 

ql Desktop 

@ clif 

x Applications 
[3] Documents 
SEARCH FOR 


Diet 


Enable: | All Files 34 
Open 


14.1.4 tk_getSaveFile 


This file-browsing widget returns the name of a selected file. If the selected file already exists, users 
are prompted to confirm that they are willing to overwrite the file. This widget creates a new window 
that is identical to the window created by tk_getOpenFile. 


Syntax: tk_getSaveFile ?option value? 
Create a file-browsing widget to find an existing file or enter the name of a nonexistent 
file. 
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?option value? The tk-getSaveFile megawidget supports the same options as 
the tk_getOpenFi le widget. 


14.1.5 tk_messageBox 
The tk_messageBox command creates a dialog window in one of several predefined styles. This 
command returns the name of the button that was clicked. This command creates a new window that 
takes focus until interaction with this widget is complete. 
Syntax: tk_messageBox ?option value? 
Create a new window with a message and a set of buttons. When a button is clicked, 
the window is destroyed and the value of the button that was clicked is returned to the 
script that created this widget. 
option value 
Options for this widget include: 


-message The message to display in the box. 
-title The title to display in the window border. 
-type The type of message box to create. The type of box will 


determine what buttons are created. The options are: 
abortretryignore Displays three buttons: abort, retry, and ignore. 


ok Displays one button: ok. 

okcancel Displays two buttons: ok and cancel. 
retrycancel Displays two buttons: retry and cancel. 
yesno Displays two buttons: yes and no. 
yesnocancel Displays three buttons: yes, no, and cancel. 


———— ee eee ee eee 
Example 4 


Script Example 
set clicked \ 
[tk_messageBox -message "Continue Examples?" -type yesno] 


Script Output 
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Continue Examples? 


14.1.6 tk_dialog 


The tk_dialog megawidget creates a message window with a line of text, and one or more buttons 
labeled with text provided in the command line. When the user clicks a button, the button position is 
returned. The first button is number 0. If the user destroys the window, a —1 is returned. This command 
creates a new window in the center of the screen and disables the other windows in the task that invoked 
it until interaction with this widget is complete. 


Syntax: tk_.dialogwin title text bitmap default stringl ?...stringN? 

Create a dialog box and wait until the user clicks a button or destroys the box. 

win The name for this dialog box widget. 

title A string to place in the border of the new window. Whether or not the 
window is displayed with a border depends on the window manager 
you are using. 

text The text to display in the message box. 

bitmap If this is not an empty string, it must be a bitmap object or bitmap file 
name (not an image object) to display. 

default A numeric value that describes the default button choice for this 
window. The buttons are numbered from 0. 

stringx The strings to place in the buttons. 
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Example 5 
Script Example 
set reply [tk_dialog .box "Example Dialog" \ 
"Who’s on first?" \ 
questhead 0 "Yes" "No" "Don’t Know" ] 


Who's on first? 


{ No ) ( Don't Know ) 


14.1.7 tk_popup 


The tk_popup command creates a pop-up menu window at a given location on the display (not con- 
strained within the wish window). The menu appears with a tear-off entry and takes focus. Note that 
this widget is not modal. The command after the tk_popup is evaluated immediately without waiting 
for the user to select an item from the menu. The following example shows the pop-up bound to a left 
button press to display a question based on the content of a text widget. 
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Syntax: tk_popup menu x y ?entry? 
tk_popup Create a pop-up menu somewhere on the display. This need not be 
within the Tcl/Tk application window. 


menu A previously defined menu object. 
xX y The x and y coordinates for the menu in screen coordinates. 


?entry? A numeric value that defines a position in the menu. The defined 
position will be selected (active), and the menu will be placed with that 
entry at the x, y position requested. 


ae 
Example 6 
Script Example 
proc question {} { 

global var; 

jf Remove any existing .m menu. 

i## Use catch in case there is no previous .m menu. 

catch {destroy .m} 


i## Create a menu for this popup selector 
menu .m 
.m add command -font {helvetica 14} \ 
-label {This dialog is from Abbott & Costello’s \ 
"Who’s on First?" routine} \ 
-command {tk_messageBox -type ok -message "Correct"} 
.m add comma 
-label "T 
-command 
.m add comma 
: 
d 


{ 
d -font {helvetica 14} \ 

his dialog is from _War_and_Peace_" \ 
{tk_messageBox -type ok -message "Wrong"} 
d 

] 

{ 


-font {helvetica 14} -label \ 
is from Monty Python’s Parrot sketch" \ 
essageBox -type ok -message "Wrong"} 


"This di 
-comman 


if Get the size and location of this window with the "winfo" 
df command, which returns the geometry as 
df =WIDTHXHEIGHT+XPOS+Y POS 
if The scan command is similar to the C standard 
if library "sscanf" function. 


scan Lwinfo geometry .] “%dx%d+%d+%d" \ 
width height xpos ypos 


i## Put the popup near the bottom, right hand 

i## edge of the parent window. 

tk_popup .m [expr $xpos + ($width/2) + 50 J \ 
Lexpr $ypos + $height - 40] 1 
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dt Create a text window, display it, and insert some text 
if from a famous dialog. 


text .t -height 12 -width 75 -font {helvetica 14} 
grid .t 
set dialog { 


"C: Tell me the names of the ballplayers on this team. \n" 
"A: We have Who on first, What’s on second, “ 

"IT Don’t Know is on third.\n" 

"C: That’s what I want to find out.\n" 

"T want you to tell me the names of the fellows" 

on the team. \n" 
"A: I’m telling you. Who’s on first, " 
"What’s on second, Don’ t\n" 

"Know is on third -\,-\n" 

"C: You know the fellows’ names?\n" 


"A: Yes.\n" 
"C: Well, then who’s playin’ first. \n" 
"A: Yes.\n" 


} 


foreach line $dialog { 
.t insert end $line 


## Bind the right button to a question about this dialog. 
bind .t <Button-1> question 


Script Output 


IC: Tell me the names of the ballplayers on this team. 

A: We have Who on first, What's on second, | Don't Know is on third. 
IC: That's what | want to find out. 

| want you to tell me the names of the fellows on the team. 

A: I'm telling you. Who's on first, What's on second, | Don't 


Know is on third -,- 

IC: You know the fellows’ names? 
A: Yes. 

IC: Well, then who's playin’ first. 
A: Yes. 
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: Tell me the names of the ballplayers on this team. 

: We have Who's on first, What's on second, I Don't Know is on third. 
: That's what I want to find out. 

I want you to tell me the names of the fellows on the team. 
A: I'm telling you. Who's on first, What's on second, I Don't 

Know is on third -— 
Cc: You know the fel] tearoffl 
A: Yes. This dialog is from Abbott & Costello's "Who's on First?" routine 
iC: Well, then who's 
A: Yes. 


This dialog is from _War_and_Peace_ 
This dialog is from Monty Python's Parrot sketch 


C: Tell me the names of the ballplayers on this team. 

A: We have Who on first, What's on second, | Don't Know is on third. 
C: That's what | want to find out. 

| want you to tell me the names of the follows on the team. 

A: I'm telling you. Who's on first, What’ ff = 


i] 
Know is on third -,- 


C: You know the fellows' names? | 1) Correct 
A: Yes. 
C: Well, then who's playin’ first. Po | 
A: Yes. l 


14.2 MEGAWIDGET BUILDING PHILOSOPHY 


The megawidgets included in the standard distribution are useful, but the odds are good that you will 
end up needing to build your own widgets at some point. You can design a megawidget library in a 
number of ways. Each technique has features that may make it better or worse for your application. 
One of the primary trade-offs is versatility and ease of use versus speed of construction. If you expect 
to use the widget more than once, it is worthwhile to take the extra time to design the widget library 
for versatility. Consider the points discussed in the sections that follow when building your widget 
libraries. 


14.2.1 Display in Application Window or Main Display? 


The Tk distribution includes several megawidgets that open their own windows on the primary display 
rather than being loaded into the application window. Some widgets are useful as temporary top-level 
windows, whereas others are more useful if they can be packed into an application window. 

A fallback position is to design a widget to be loaded in an existing window. You can create a 
wrapper to create anew toplevel window and pack the widget into that window when you need a 


Pop-up. 
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14.2.2 Modal versus Modeless Operation 


Most of the megawidgets in the standard Tk distribution operate in a modal style, freezing any other 
activities until the user has completed an interaction with this widget. This is appropriate behavior in 
some circumstances but not in others. Consider the applications in which your megawidget will be 
used to determine whether modal or modeless operation is required, or if script writers should be able 
to define the behavior, when they create the widget. 


14.2.3 Widget Access Conventions 

You can design a megawidget to follow its own conventions, or it can mimic the behavior of the 
standard Tk widgets. The widget creation command can return a handle that is used to identify this 
megawidget to procedures that manipulate it. Code using this technique would resemble the following. 


set megaHandle [megaCreate -option value] 
myMegaConfigureProc $megaHandle -newOption -newValue 


The examples in this chapter demonstrate a better technique. They construct megawidgets that 
return the name of a procedure that accesses the megawidget. This technique mimics the behavior of 
the standard widgets and is implemented with the object-style technique introduced in Chapters 7 — 10. 
Code using this technique would resemble the following. 


set mega [newMegaWidget -option value] 
$mega configure -newOption newValue 


14.2.4 Widget Frames 

Most megawidgets have a parent frame that holds their subwidgets. This frame can be created by the 
megawidget creation command or provided by the calling procedure. If the frame is created by the 
widget creation command, calling script can provide the name (as names are given to Tk widgets) or 
the megawidget can generate a unique name. 

If you provide the parent frame for the megawidget (instead of just providing a name), you can 
have the megawidget display itself in that frame automatically. This is not a generally good technique. 
It restricts the usefulness of the widget to applications that have similar display requirements. This 
technique is useful for widgets such as toolbar buttons that are always displayed side by side in a 
frame. 


14.2.5 Configuration 

The next person who uses your megawidget library is guaranteed not to like the configuration options 
you chose. For instance, the dialog box that informs users that the warp drives are about to explode 
and asks whether they would like do something about it should probably be in a bright color with big 
letters, rather than the usual dull gray with small letters. Configuration options can be: 


e Set in a state variable and applied when the widget is created 

e Set on the widget creation command line 

e Set in a configure procedure associated with the widget 

e Set with the option add command (discussed in Section 14.3.2) if the megawidget must use the 
-class option to define itself as a new class of widget 
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Supporting the first two and fourth options of the previous list is the most versatile design. This 
provides features that mimic the options supported by the normal Tk widgets. 


14.2.6 Access to Subwidgets 

A megawidget can be designed in an opaque manner, so that the component widgets cannot be 
accessed, or in a transparent manner so that the component widgets can be accessed and modified. 
If the goal of this megawidget is to provide a uniform interface across all applications that use it, the 
widget should be designed to restrict programmers from modifying the options of the subwidgets. The 
message box and file browsers provided by the OS platform are examples of this style of widget. 

If the goal for this megawidget is to provide a tool for a wide variety of applications, the megawidget 
should be designed to allow the application script writer access to the subwidgets. This allows the 
application writer to modify options such as background color and font. This can be handled by the 
techniques described in the following. 


Naming Convention 
The megawidget creation command returns a base name for the megawidget. The subwidgets are 
accessed as base.labelName, base.buttonOK, and so on. This is the simplest technique to 
implement, although it may be difficult to use if you nest megawidgets within other megawidgets. 
This technique’s disadvantage is that it requires application-level code to know about the internals 
of the megawidget. This can make maintenance a headache. 
Code using this technique might resemble: 


set w LmyMegaWidget .meg -option value] 
$w.topLabel configure -font $bigFont 


A Command to Return Subwidget Names 

The megawidget package you design can include a subwidget command that will return the full 
name of a subwidget component of the megawidget. Code that uses this technique would resemble the 
following. 


set button [$myMegaWidget subwidget buttonOK] 
$button configure -text "A-OK" 


Pass Commands to the Subwidget 
The widget procedure can accept a list of subwidgets and command strings to be evaluated by the 
subwidget. Code that uses this technique would resemble the following. 


set myBigWidget [megawidget .bigwidget -option value] 
$myBigWidget widgetcmd mainTitle configure -text "Big Widget" 


Subwidget Option 
The widget procedures you create can accept (or require) a subwidget as an argument when they are 
invoked. Code that uses this technique would resemble the following. 


$myMegawidget configure -subwidget buttonOK -text "A-OK" 
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14.2.7 Following Tk Conventions 


The closer you follow the Tk conventions for names, options, and subcommands, the easier it is 
for script writers to use your megawidgets. If there are two equally good methods for creating the 
functionality you need, choose the one that mimics Tk. 


FUNCTIONALITY THAT MAKES MEGAWIDGETS POSSIBLE 


Tcl/Tk provides three sets of functionality that make it easy to build megawidgets with pure Tcl. All 
of these pieces have other, perhaps more important, uses, but they work together synergistically when 
used to construct megawidgets. The three features are the rename command, the option command, 
and the -class option. 


3.1 The rename Command 


The rename command was discussed briefly in Chapter 7. 

We can also use the rename command to rename the command associated with a widget. For 
instance, in the next code snippet, a label named .1 is created with the command label .1 -text 
"original". This creates both a widget named .1 and acommand named .1. The rename command 
renames the procedure .1 to mylabel. The widget is still named .1, and that name must be used to 
pack the widget. However, the procedure is now named my1abel, and that is the name we must use 
to configure the widget. 


label .1 -text "original" 
rename .1 mylabel 
pack .1 


mylabel configure -text "new text" 


When creating megawidgets, we will first create a frame to hold the widget components, and then 
rename that frame’s procedure to something new, so that we can define a new command with the 
original name of the frame as the widget command. Stripping it down below the bare essentials, the 
following shows what happens. 


=—$£—_——_ > Ss 
Example 7 
Script Example 

if Create a frame to hold the subwidgets. 

frame .megawidget 

# ... Build and display the subwidgets 

i## Rename the frame procedure to a new name. 

rename .megawidget megaWidgetFrame 

it Create a new procedure named for the original frame. 

proc .megawidget {...} {...} 
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4 The option Command 


The option command lets the Tcl programmer interact with the Tk option database. The option 
database is a collection of patterns and values. When the wish interpreter creates a new window, it 
examines the options database to see if this window has any configuration options that match a pattern 
in the database. The value from the database is applied to the widget if an option is matched. You can 
set a value in the option database with the option add command. 


Syntax: option add pattern value ?priority? 
Add a definition to the options database. 
pattern The pattern describing the widget option to set. 
value A value to use when a widget that matches the pattern is created. 


The form of a pattern is appl ication.widget.optionName. The pattern tkcon.mybutton. 
background would match the background color of a button named .mybutton in an application 
named tkcon. The basic pattern supports a few variations to make it more versatile. 


e Any field can be replaced by a wildcard (*). Thus, xmybutton.background would match the 
background of any button named .mybutton. 

e Fields can be replaced by a generic name. The generic name will start with an uppercase letter. The 
generic name for a widget field is the name of the class of the object. For example, 


«Button. background will match the background of any button created in an application. 


The Tcl interpreter will select options from the most specific pattern that matches a widget. Thus, 
using a widget name will override a generic widget option, as shown in the following example. 


$$ 
Example 8 
Script Example 
if All labels have white background 
option add *xLabel*background white 
if All widgets named alert have black background 
if and white foreground 
option add xalertxbackground black 
option add xalertxforeground white 
pack [label .1 -text "normal colors"] 
pack [label .alert -text "ALERT Inverted" ] 


Script Output 


normal colors 


ALERT Inverted 


The option add command can be used in any application when you want to change the default 
value for a set of widgets. For example, if you want to make large buttons you might use the - font 
option for each button command, or you could set the xButton*Font option to a larger font. One 
advantage of using the option command is that it is faster than using - option in a widget creation 


14.4 Building a Megawidget 511 


command. In an application with many widgets, this can noticeably affect how quickly windows are 
built. 


3 The -class Option 
The Tcl interpreter can assign a -c lass option toanew frame or toplevel widget. The default class 
for a frame is Frame, and the default class for a top-level window is Toplevel. (This information is 
returned by the winfo class widgetName command.) 

If we include the -class option with the frame or toplevel command, our script can override 
this to become a new class. We can set options for all members of this new class with the option add 
command. 


.——_a—_ 
Example 9 
Script Example 
## A simple Label/Entry megawidget 
proc LabelEntry {frameName labelText varName} { 
frame $frameName -class Labelentry 
pack [label $frameName.1] -text $labelText] -side left 
pack Lentry $frameName.e -textvar $varName] -side left 
return $frameName 
} 


if Labelentry widgets all use large font 
option add xLabelentryxfont {Times 24 bold} 
pack [LLabelEntry .le "Enter your Name" name] 


Script Output 


nter your Name 
= 


14.4 BUILDING A MEGAWIDGET 


The simple LabelEntry megawidget shown in the previous example makes it easier to develop a 
form-style application with many items to be filled out. Using this type of simple megawidget can 
make your applications easier to write and maintain. However, if you are developing a library of 
complex megawidgets for multiple projects, you will want them to be more flexible. 

The first step in designing a library of megawidgets is deciding what sets of conventions you will 
follow. The actual conventions do not matter as much as consistently following the conventions. Con- 
sistency is one of the keys to creating a usable set of tools. This section describes building a modeless 
megawidget in a frame. This widget will behave like one of the basic Tk widgets. The conventions we 
will establish for this widget are as follows. 
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e The subwidget will create a new frame of class Megawidget. 

e A configuration option can be defined for the entire megawidget and it will be propagated to all 
appropriate subwidgets using the option command. 

e A subwidget is identified by a unique identifier within the megawidget. For example, .paren- 
twindow.megawidget.subwidget will be identified as subwidget. 

e A list of subwidget names will be returned by a names command, similar to array names. 

e Subwidgets may also be accessed by full name. For example, 
.parentwindow.megawidget.subwidget may be identified as 
.parentwindow.megawidget.subwidget. 

e A configuration option can be defined for a subwidget with a widgetconfigure command that 
duplicates the behavior of the configure command. 

e A configuration option can be queried for a subwidget with a widgetcget command that 
duplicates the behavior of the cget command. 

e Acommand can be passed to a subwidget with the widgetcommand command. 

e Infrastructure data and procedures will be maintained in a namespace. 


14.5 A SCROLLING 1istbox MEGAWIDGET 


This section shows how a megawidget can be built using the conventions described in Section 14.4. The 
first example creates a simple scrolling 1 istbox megawidget. The next example enhances this widget 
into a more complex megawidget that can take selected items from one scrolled listbox and place them 
in another. The final example puts a wrapper around that megawidget to make a modal file selector. 


14.5.1 Scrolled listbox Description 


The scrollable 1 istbox megawidget we will construct will mimic the structure of the Tk widgets. The 
support procedures for this megawidget exist within a namespace. A single procedure (scrol1edLB) 
exists in the global scope to create a scrol1edLB megawidget. 

The scrol1edLB procedure will return the name of the new widget’s parent frame and will create 
a procedure with that name in the global scope. This procedure will support several subcommands in 
the same manner as the Tk widgets. The scrol1edLB configuration options can be set by: 


e Using the option add command before constructing a scrol1edLB widget. 

e Using new options defined for this megawidget. 

e Using the widgetconfigure widget subcommand after constructing a scrol 1 edLB widget. 

e Retrieving the full path of a subwidget with the subwidget command and using that widget’s 
configure subcommand. 


The scrolledLB procedure accepts any configuration values that are valid for a frame or that 
match specific options for this megawidget, and uses those values to configure the frame or the 
scrollbar and 1istbox subwidgets. In addition, the scrol]ledLB command accepts an option to 
define whether the scrollbar should be on the left or right side of the listbox. 


Syntax: scrolledLB ?frameName? ?-option value? 
Create a scrol1edLB megawidget. Returns the name of the parent frame for this wid- 
get for use with the pack, grid, or place layout managers and creates a procedure 
with the same name to be used to interact with the megawidget. 
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?frameName? An optional name for this widget. If this argument is not 
present, the widget will be created as a unique child of the root 


“eo 9 


frame, “.”’. 


?-option value? Sets of configuration values that can be applied to the scrollbar 
or listbox. 


The widget procedure created by the scrol1edLB command will accept the subcommands confi g- 
ure, widgetconfigure, widgetcget, widgetcommand, names, insert, delete, selec- 
tion, and subwidget. 

The scrolledLB widget widgetconfigure and widgetcget subcommands are similar to the 
standard Tk configure and cget commands except that they accept a subwidget argument. The 
configuration options will be applied only to those subwidgets. 


Syntax: scro]]edlLBNamewidgetconfigure subwidgetName ?-opt? ?val? 
Return the value of an option, or set an option if a value is supplied. 


subwidgetName ‘The name of a subwidget or subwidgets to be configured or 
queried. If the widget is being queried and multiple subwidget 
names are present, the return value will be a list of 
configurations in the order in which the subwidgets appear in the 
list. 


NOTE: This field is different from standard widget usage. 

-opt An option name. If multiple options are being set, there may be 
multiple -opt val pairs. If the configuration is being queried, 
only one - opt argument may be present. 


val The value to assign to a configuration option. 


The insert and delete subcommands pass their arguments to the 1istbox subwidget with no 
further parsing. Thus, they exactly duplicate the behavior of the 11s tbox subcommands. 


Syntax: scro]ledLBName insert index string 
Inserts an item into the 1istbox at the requested index position. 
index The location in the list before which this entry will be inserted. Any index 
value appropriate for a 1istbox widget may be used. 


string The text to insert into that location of the listbox. 


Syntax: scro]ledlBName delete first ?last? 
Delete one or more items from the listbox. 
first The index of the first item to delete. The listbox items are numbered 
from 0. 


?last? The index of the last item in a range to delete. If this argument is not 
present, only the item identified by the first is deleted. 


The selection subcommand returns the content of the selected entries of the listbox. Note that the 
listbox curselection subcommand returns a list of the indices of selected items, whereas this 
selection returns a list of the content. 
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Syntax: scro]]edLBName selection 
Returns the text of the selected item or items from the listbox. 


The subwidget subcommand returns the full path name of a subwidget of the scrol]edLB. 


Syntax: scro]ledLBName subwidget name 
Returns the full name of a subwidget of this scrol]edLB. 
name The name of the subwidget to return. May be one of: 
list The full name of the 1istbox widget. 
scrollbar The full name of the scrollbar widget. 
title The full name of the 1 abel widget. 


14.5.2 Using the scrolledLB 


The next example shows how to use the scrolled listbox. The widget creation command resembles that 
of a standard Tk widget. 


OOOO —-.”——n—n— OO ay»->——= 
Example 10 


Script Example 


i## set the auto_path and declare that we require the 

i## scrolledLB package. 

i## The widget pkgIndex.tcl file is in the current directory 
i## Load the scrolledLB support 


lappend auto_path. 
package require scrolledLB 


if The background of the listbox is white 
if The other widgets are normal gray. 
option add *Scrolled|lb*Listbox*background white 


## Create and pack the scrolled listbox 

set 1b [LscrolledLB .sbox -listboxHeight 5 -listboxWidth 20 \ 
-titleText "Pick your Banjo"] 

grid $1b 


## Fill the listbox 
foreach brand { {Bacon & Day} Epiphone Gibson \ 
Ludwig Paramount Orpheum Vega Weymann} { 
$1b insert end $brand 
} 


if Add a button to display the selection 
set cmd [format {puts "Picking an [%s selection]"} $1b] 
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button .b -text "Output Selection" -command $cmd 


grid .b 


Script Output 
Picking an Orpheum 


Pick your Banjo 


Output Selection | 
| 


14.5.3 Implementing the Scrollable 1 istbox 


The scrolledLB widget is implemented using a common pattern for widgets and data structures 
that mimic objects. There is a single global scope procedure to create the scrol]1edLB megawidget, 
and a set of support procedures for the scroll]edLB in a private namespace. Creating a megawidget 
also creates a new procedure in the global scope with the same name as the parent frame. The new 
procedure invokes support procedures in the widget namespace scope. The scrol1edLB megawidget 
is implemented with state variable and three procedures. 

The state variable, scrol]ledLBState, exists within the scrol1ledLB namespace. This variable 
holds the information that needs to be maintained between evaluations of the scripts in this package. 
This information includes a number used to create unique names for the scrol1ledLB widgets when 
no name is provided in the creation command line, and a lookup table to map simple subwidget names 
such as 11st to the full widget path, such as . fi leFrame.sbox.1ist. The scrolledLB procedure 
that creates a scrol1edLB widget exists in the global scope. 

The scrolledLB procedure calls the MakescrolledLB procedure in the widget namespace. 
The MakescrolledLB procedure creates the new megawidget and returns the widget name to the 
scrolledLB procedure. The scrol1edLB procedure uses that name to create a new procedure in the 
global scope that will interact with the new megawidget. The new procedure interacts with the widget 
by invoking the widgetNameProc procedure that exists in the widget namespace. 

The MakescrolledLB procedure creates a frame to hold the subwidgets that constitute this 
megawidget. That frame should have the same name as the megawidget. This lets us access the 
subwidgets as children of the parent megawidget. 

However, there is a name conflict when you use the same name for both the megawidget and the 
frame that contains the megawidget components. The trick is that we want the megawidget to look 
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like a Tk object, but the megawidgets in these examples are frames holding some subwidgets and a 
procedure to access the subwidgets. 

For instance, if you construct a megawidget named . foo and create the subwidgets within a frame 
named .f00, you cannot use . foo as the procedure name for the megawidget commands. The com- 
mand name . f00 is already in use by the frame . foo, and Tcl command and procedure names may 
not conflict. We solve the problem by renaming the procedure associated with the holder frame to a 
new name, and then writing a new procedure with the original name to interact with the megawidget. 

This creates a naming convention that makes the frame and subwidgets appear as children to 
the megawidget. This is the way the megawidget and subwidgets are related to each other logically, 
although it is not the way the megawidget is implemented. The Makescrol1edLB procedure creates a 
frame to hold the subwidgets and then renames the widget procedure associated with that frame before 
returning the frame name to the scrol1edLB procedure. The scrol1edLB procedure is evaluated in 
the global scope, and when it creates a new procedure with the name of the holder frame that procedure 
is created in the global scope. 

For example, if your script invokes scrol1edLB to create a scrol1ledLB named .s11, the Make- 
scrolledLB command will create a frame named .s11. After the scrollbar and listbox have been 
packed into the frame .s11, it will rename the frame widget command from .s11 to .s11.fr. Since 
there is no longer a procedure named .s11, the scrolledLB procedure can create a new procedure 
named .s11 that will invoke scrol1edLBProc to process the megawidget commands. 

We can do this because procedure names and window names are resolved from separate tables. 
When you create a frame . foo, the Tk interpreter creates a window named . foo and a procedure 
named .f0o0 to access that window. You can rename the procedure .foo without affecting the 
window . foo. 

Being able to disconnect the frame .s11 from the procedure .s11 allows us to duplicate the Tk 
convention of declaring a name for the megawidget and then using that name as the widget procedure. 
If we did not rename the frame widget procedure there would be no way to interact with the frame after 
we create a new procedure with that name. 

After MakescrolledLB has created a frame to hold the subwidgets, it returns the name of the 
parent frame to scrolledLB, which creates a procedure in the global scope with the same name as 
the frame. This new procedure is the global portion of the second pair of procedures. Script writ- 
ers will use this procedure when they need to interact with the megawidget. This procedure simply 
invokes scrolledLBProc, a procedure in the scrolledLB namespace to actually implement the 
widget commands. 


Global Scope scrolledLB Namespace 

scrolledLBName scrolledLBProc 

Accepts the scrolledLB widget Performs the widget interactions requested by 
subcommands. the widget subcommands. 


Invokes scrolledLBProc to pro- 
cess the command with the name of 
the parent frame. 


These procedures are all that is needed to create a scrolled 1 i stbox megawidget. The actual imple- 
mentation is broken up into few more procedures within the scrolledLB namespace just to make 
maintenance simpler. 
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14.5.4 The scrolledLB Code 


The actual implementation of this code is broken up into a couple more procedures. Draw creates and 
maps the subwidgets into the parent frame, and DoWidgetCommand implements the widgetcommand 
subcommand. 


eee eee 
Example 11 


Script Example 
if Name: Scrolled LB. tcl 


package provide scrolledLB 1.0 


JHA HAAR AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA 
## proc scrolledLB {args} 

if Create a scrolledLB megawidget 

i## External entry point for creating a megawidget. 

df Arguments 

it ?parentFrame? A frame to use for the parent, 


if If this is not provided, the mega widget 

if is a child of the root frame ("."). 

dt 

if args A set of key/value pairs to describe the listbox 
dt 

if Results 


## Creates a procedure with the megawidget name for processing 
if widget commands 
if Returns the name of the megawidget 


proc scrolledLB {args} { 
set newWidget [eval scrolledLB::MakescrolledLB $args] 


if Define a new command which passes control to the 
# scrolledLB::scrolledLBProc command and return the results. 


set newCmd [format {return [namespace eval %s “4S %S $args ]}\ 
scrolledLB scrolledLBProc $newWidget ] 


proc $newWidget {args} $newCmd 


return $newWidget 
} 


namespace eval scrolledLB { 
variable scrolledLBState 


i## Assign a couple defaults 
set scrolledLBState(unique) 0 
set scrolledLBState(debug) 0 
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Hi MMMM MaMa aa aaal 
i## proc MakescrolledLB {args} 
it Create a scrolledLB megawidget 
if Arguments 
it ?parentFrame? A frame to use for the parent. 
if If this is not provided the megawidget 
i is a child of the root frame ("."). 
i## =?-scrollSide left/right? 
ld The side of the listbox for the scrollbar 
if Results 
i## Returns the name of the parent frame for use as a 
it ~megawidget 
proc MakescrolledLB {args} { 
variable scrolledLBState 


it Set the default name 
set holder .scrolledLB_$scrolledLBState(unique) 
incr scrolledLBState(uni que) 


## If the first argument is a window path, use that as 
i## the base name for this widget. 
if {[string first "." [lindex $args 0]] == 0} { 

set holder Llindex $args 0] 

set args [lreplace $args 0 0] 


} 


4 Set Command line option defaults here 
if height and width are freebies 
set scrolledLBState($holder.height) 5 

set scrolledLBState($holder.width) 20 

set scrolledLBState($holder.scrollSide) 1 
set scrolledLBState($holder.listboxHeight) 10 
set scrolledLBState($holder.listboxWidth) 20 
set scrolledLBState($holder.listSide) 0 

set scrolledLBState( tleText) title 


holder.ti 


foreach {key val } $args { 
set keyName [string range $key end] 
if {!Linfo exists \ 
scrolledLBState($holder.$keyName)]} { 
regsub -all "$holder." \ 
[array names scrolledLBState $holder.*] \ 
"OK LESE 
error "Bad option" \ 
"Invalid option ’$key’.\n\ 
Must be one of $o0kList" 
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} 
set scrolledLBState($holder.$keyName) $val 
} 


i Create master Frame 

frame $holder -height $scrolledLBState($holder.height) \ 
-width $scrolledLBState($holder.width) \ 
-class ScrolledLB 


# Apply invocation options to the master frame, as appropriate 
foreach {opt val} $args { 

catch {$holder configure $opt $val} 
} 


Draw $holder 


if We can’t have two widgets with the same name. 
it Rename the base frame procedure for this 

## widget to $holder.fr so that we can use 

ft $holder as the widget procedure name 

i# for the megawidget. 
uplevel #0 rename $holder $holder.fr 


i## When this window is destroyed, 
if destroy the associated command. 
bind $holder <Destroy> "+ rename $holder {}" 
return $holder 

} 


{HAHAHA AAA AAR AAR AAA AAA AAA AAA AAA AAA AAA 
# proc Draw {parent} -- 
# creates the subwidgets and maps them into the parent 
i Arguments 
## parent The parent frame for these widgets 
tf 
## Results 
i## New windows are created and mapped. 
proc Draw {parent} { 
variable scrolledLBState 


set tmp [scrollbar $parent.yscroll -orient vertical \ 
-command "$parent.list yview" ] 


set scrolledLBState($parent.subWidgetName.yscroll) $tmp 
grid $tmp -row 1 -sticky ns \ 
-column $scrolledLBState($parent.scrollSide) 
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set tmp Llistbox $parent.list  \ 
-yscrollcommand "$parent.yscroll set" \ 
-height $scrolledLBState($parent.listboxHeight)\ 
-width $scrolledLBState($parent.listboxWidth) ] 


set scrolledLBState($parent.subWidgetName.list) $tmp 
grid $tmp -row 1 -column $scrolledLBState($parent.listSide) 


set tmp [label $parent.title \ 
-text $scrolledLBState($parent.titleText) ] 


set scrolledLBState($parent.subWidgetName.title) $tmp 
grid $tmp -row 0 -column 0 -columnspan 2 
} 


HMMM MMM ae aa Maal 
# proc DoWidgetCommand {widgetName widgets cmd} -- 

i## Perform operations on subwidgets 

if Arguments 

if widgetName: The name of the holder frame 


i## widgets: A list of the public names for subwidgets 

if =ocmd: A command to evaluate on each of these widgets 
i 

i## Results 


i## Does stuff about the subwidgets 


proc DoWidgetCommand {widgetName widgets cmd} { 
variable scrolledLBState 
foreach widget $widgets { 
set index $widgetName.subWidgetName. $widget 
eval $scrolledLBState($index) $cmd 


} 


proc selection {widgetName} { 
set Ist [$widgetName.list curselection] 
set itemlst "" 
foreach 1 $lst { 
lappend itemlst [$widgetName.list get $1] 
} 
return $itemlst 
} 


MMe aaa aaaG 
## proc scrolledLBProc {widgetName subCommand args} 

i## The master procedure for handling this megawidget’s 

if =subcommands 


i## Argume 
if widge 
if wid 
if =subCo 
# args: 
# arg 
if Defau 
## config 
if widge 
if eg 
it eg 
if widge 
# eg 
if widge 
la eg 
if names 
i ap 
fl eg 
tf eg 
if wi 
if subwid 
+ req 
# Resul 
if Eval 
proc scr 
variab 
set c 
switch 
conf 
r 
} 
widg 
S 
S 
S 
C 
r 
} 
dele 
inse 
7 
} 
sele 
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nts 

tName: The name of the scrolledLB 

get 

mand The subCommand for this cmd 
The rest of the command line 

ments 

t subCommands are: 

re - configure the parent frame 


tconfigure - configure or query a subwidget. 


a widgetconfigure itemID -key value 
a widgetconfigure itemID -key 


tcget - get the configuration of a widget 


a widgetcget itemID -key 


tcommand - perform a command on a widget 


a widgetcommand itemID commandString 
- return the name or names that match 
attern 
a names # Get names of all widgets 
a names xa* # Get names of widgets 


th an ‘a’ in them. 


get - return the full pathname of a 
uested subwidget 


ts 
ates a subcommand and returns a result if required. 


olledLBProc {widgetName subCommand args} { 
le scrolledLBState 
dArgs $args 


-- $subCommand { 
igure { 
eturn Leval $widgetName.fr configure $cmdArgs ] 


etconfigure { 

et sbwid [Llindex $cmdArgs 0] 

et cmd [lrange $cmdArgs 1 end] 

et index $widgetName.subWidgetName.$sbwid 

atch {eval \ 

$scrolledLBState($index) configure $cmd}  rtn 
eturn $rtn 


eturn Leval $widgetName.list $subCommand $cmdArgs ] 


ction {return [selection $widgetName]} 
etcget { 
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if {Lllength $cmdArgs] != 2} { 
error "$widgetName cget subWidgetName -option" 

} 
set sbwid Llindex $cmdArgs 0] 
set index $widgetName.subWidgetName. $sbwid 
set cmd [Llrange $cmdArgs 1 end] 
catch {eval \ 
$scrolledLBState($index) \ 

cget $cmd} rtn 

return $rtn 

} 
widgetcommand { 

return [eval DoWidgetCommand $widgetName $cmdArgs ] 


} 
names { 
if {{string match $cmdArgs ""]} { 
set pattern $widgetName.subWidgetName. x 
} else { 
set pattern $widgetName.subWidgetName.$cmdArgs 
} 
foreach n [array names scrolledLBState $pattern] { 
foreach {d ws name} [split $n .] {} 
lappend names $name 
} 
return $names 
} 
subwidget { 
set name [lindex $cmdArgs 0] 
set index $widgetName.subWidgetName. $name 
if {Linfo exists scrolledLBState($index)]} { 
return $scrolledLBState($index) 


} 
default { 
error "bad command" "Invalid Command: \ 

$subCommand \ n \ 
must be configure, widgetconfigure, \ 
widgetcget, names, \ 
delete, insert, selection, \ 
or subwidget" 
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4.6 NAMESPACES AND TK WIDGETS 


When the command associated with a Tk widget is evaluated, it is evaluated in the global namespace 
even if the widget is created inside a namespace. For example, the following code will not work. 


namespace eval badCode { 

variable clicked 0 

button .b -text "Click me" -command "set clicked 1" 
} 


When the button is clicked, it will create and assign a | to the variable clicked in the global scope, 
not assign a | to the variable clicked in the namespace badCode. There are two namespace sub- 
commands that provide the hooks for using Tk widgets and namespaces. The namespace current 
command will return the current namespace, and namespace code script will make a script that 
will be evaluated in the current namespace. 


Syntax: namespace current 
Returns the absolute name of the current namespace. 


The previous example can be modified to use the namespace current command to set the correct 
variable. After performing substitutions, the script registered with the button is set ::good- 
Code::clicked 1. 


:—_——_ AS A A A a Ss 
Example 12 
namespace eval goodCode { 
variable clicked 0 
button .b -text "Click me" \ 
-command “set [namespace current]::clicked 1" 


The namespace code command will wrap a script with some namespace commands to force the 
script to be evaluated in the current namespace, instead of the namespace it’s invoked from. 


Syntax: namespace code script 
Returns a script that will be evaluated in the current namespace. 
script The script to be evaluated. 


The first example can also be modified to work using the namespace code command. In the following 
example, the 
namespace code {set clicked 1} 
script is converted to 
namespace inscope ::goodCode {set clicked 1}, 
which is the script registered with the button. This is equivalent to : 
namespace eval ::goodCode {set clicked lf}. 
The inscope subcommand causes a script to be evaluated within an existing scope. It is usually 
used by the namespace procedures, not applications programmers. 
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namespace eval goodCode { 
variable clicked 0 
button .b -text "Click me" \ 
-command "[namespace code {set clicked 1}]" 


You will usually use namespace current when you need to provide a variable name to a Tk 
widget (for example, the -textvariable option), andnamespace code with scripts associated with 
Tk widgets. If the script associated with a widget simply invokes a procedure within a namespace, you 
can use the namespace current command to add the namespace information to the procedure name. 
However, if you include Tcl commands such as for, if, foreach, and so on in your script, you must 
use namespace code. 

Recommended procedure is to use namespace code for scripts associated with widgets. Since 
scripts associated with a widget tend to grow over time, it makes code maintenance easier. 


14.6.1 Creating a Multiple Language Megawidget 
Many applications need to be distributed with support for multiple languages. Tcl has features that help 
make this easy. Tcl uses Unicode to store text strings, which makes it easy to represent non-Latin alpha- 
bets (see Section 12.4.5 for more discussion). You can use the associative array as a translation table. 
The next example is a megawidget to create forms of label/entry widget pairs in which the label 
can be displayed in one of several languages. The label text is converted using an associative array as 
a lookup table. The Draw procedure uses both the namespace code command to invoke the wor1d- 
Form::translate procedure when the trans 1 ate button is clicked, and the namespace current 
command to link the variable wor] dFormState( language) to the tk_optionMenu widget. 


AA 
Example 13 
Script Example 
proc Draw {parent} { 
variable worldFormState 
button $parent.translate \ 
-text $worldFormState($parent.buttonText) \ 
-command [namespace code [list translate $parent]] 


eo... 

tk_optionMenu $parent.options  \ 
[namespace current]::worldFormState(language) \ 
French English German Spanish 


# ee. 
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The following example shows the complete code for this megawidget, and a short test 
example. 


eee ee eee 
Example 14 


Complete code 
if name: worldForm.tcl 


package provide worldForm 1.0 


MMMM CG MMM eaaae Maal 
## proc worldForm {args} - 

if = Create a worldForm megawidget 

if External entry point for creating a megawidget. 

if Arguments 


if ?parentFrame? A frame to use for the parent, 

if If this is not provided, the megawidget 
i is a child of the root frame ("."). 

dt 

## Results 


i## Creates a procedure with the megawidget name for processing 
if widget commands 
if Returns the name of the megawidget 


proc worldForm {args} { 
set newWidget Leval worldForm::MakeworldForm $args ] 


set newCmd [format {return [namespace eval %s 4S %s $args ]} \ 
worldForm WorldFormProc $newWidget ] 


proc $newWidget {args} $newCmd 


return $newWidget 
} 


namespace eval worldForm { 
variable worldFormState 


## Assign a couple defaults 
set worldFormState(unique) 0 


MMMM MMMM aaa ael 
df proc unique {}-- 

## Return a unique number 

if Arguments 

## None 

tf 
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if Results 


i## Modifies stateVar(unique) 


iF 


proc unique 


variable worldFormState 


{} 


{ 


return [incr worldFormState(unique) ] 


} 


HMMM iM ana aa Maal 
{args } 
it Create a worldForm megawidget 


it proc MakeworldFor 


if Arguments 
if args 


if Results 


if Returns the na 


if megawidg 


proc Makewo 
variable wo 


A li 


If the fi 


If this 
is a chi 
0 


at 
rldForm {args} 
rldFormState 


st of 


dt Set the default n 


set holde 


r.wor 


arguments to define the widget. 


ame 


{ 


rst argument starts with a ".", it is 
the parent frame for the widget. 

is not provided, the megawidget 

d of the root frame ("."). 


ther args are key/value pairs 


e of the parent frame for use as a 


dForm_$worldFormState(unique) 
incr worldFormState(uni que) 


## If the first argument is a window path, use that as 

i## the base name for this widget. 

if {[string first "." [lindex $args 0]] == 0} { 
set holder Llindex $args 0] 
set args [lreplace $args 0 0] 


} 


it Set Co 
dt height 
set world 
set worl 
set worl 
set worl 
set worl 
set worl 
set worl 


and 
and 
For 
For 
For 
For 
For 
For 


For 


line 

width 
State( 
State( 
State( 
State( 
State( 
State( 
State( 


option defaults here, 

are freebies 

holder.height) 5 

holder.width) 20 

holder. buttonText) "translate" 
holder.row) 0 

holder.row) 0 

holder.row) 0 

holder.language) english 


f 


} 


oreach {key val } 


$args { 
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set keyName [string range $key 1 end] 


if Check that this is a valid key. 
s worldFormState($holder.$keyName)]} { 


if {!Linfo exist 


i## Not valid key, generate an error. 
## Extract valid keys from worldFormState array indices. 


regsub -all 


"" okList 
error "Bad op 
Must be one o 

} 
set worldFormSta 


holder." \ 

[array names worldFormState $holder.*] \ 
tion" “Invalid option ’$key’ 
fF $okList" 


dt Create master Frame 
frame $holder -height $worldFormState($holder.height) \ 


-width $worldFormState($holder.width) 


te($holder.$keyName) $val 


-\n \ 


-class WorldForm 


i Apply invocation options to the master frame, as 


# 


appropriate 


foreach {opt val} $args { 


} 


D 


catch {$holder configure $opt $val} 


raw $holder 


i## We can’t have two widgets w 
Rename the base frame procedure 
widget to $holder.fr so 


# 
# 
# 
# 


u 


# 
iF 


r 
} 


$holder as the wid 
for the megawidget. 


plevel #0 rename $holder $ho 


When this window 


"+Enamespace code [list rename $holder {}]] 


eturn $holder 


ith the 


that we 
get procedure 


der.fr 


is destroyed, 
destroy the associated com 
bind $holder <Destroy> \ 


and. 


Same name. 


for this 
can use 
name 


MMM 
# proc Draw {parent} -- 
creates the subwidgets and maps them into the parent 


i 
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if Arguments 

i## parent The parent frame for these widgets 
fl 

i# Results 
it New windows are created and mapped. 


proc Draw {parent} { 
variable worldFormState 
set tmp [button $parent.translate \ 
-text $worldFormState($parent.buttonText) \ 
-command [namespace code [list translate $parent]] ] 


set worldFormState($parent.subWidgetName.translate) $tmp 


grid $parent.translate -row $worldFormState($parent.row) \ 
-column 0 


set tmp [Ltk_optionMenu $parent.options\ 
[namespace current]::worldFormState(language) \ 
French English German Spanish ] 


set worldFormState($parent.subWidgetName.options) $tmp 


grid $parent.options -row $worldFormState($parent. row) \ 
-column 1 


} 


MMMM MMMM aa aaal 
## proc DoWidgetCommand {widgetName widgets cmd} -- 

if Perform operations on subwidgets 

if Arguments 

i## widgetName: The name of the holder frame 


i## widgets: A list of the public names for subwidgets 
i## =ocmd: A command to evaluate on each of these widgets 
i## Results 


i## Does stuff about the subwidgets 


proc DoWidgetCommand {widgetName widgets cmd} { 
variable worldFormState 
foreach widget $widgets { 
set index $widgetName.subWidgetName. $widget 
eval $worldFormState($index) $cmd 


} 


ie! 


## proc translate {parent}-- 


dt Change the labels f 
dF Arguments 

# parent: The parent 
if 
if Results 

if The labels are -con 


proc translate {parent 
variable worldFormS 


set language [string 
foreach w Lwinfo ch 
if {[string match 
set old [$w cge 

$w configure - 


} 
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rom one language to another 


widget to examine for label widgets 


figured with new text 


pf 


tate 


tolower $worldFormState( language) ] 


ildren $parent] { 


[winfo class $w] Label]} { 
t -text] 


text $worldFormState($language.$old) 


{HEAR AAA AAA AAA AA AAA AAA AAA AAA 


# proc updateXlateTabl 

if Add index/value pai 

# Arguments 

# 1st: List of langu 

i 

## Results 

jf The state array is 

proc updateXlateTable 
variable worldFormSt 


## sample: english N 
# array set State { 
i english.Nom Name 
# array set State { 
if =spanish.Nom Nombr 
## For later xlate to 
# "set word $State( 


foreach {lang word} 
set lookup "" 
foreach {1 w} $lst 

if {![Ustring ma 
lappend looku 


} 
} 
array set worldFor 


e {lst}-- 
rs to translation table 


age and word pairs 


updated 
{1st} { 
ate 


ame french Nom spanish Nombre 
english.Nombre Name } 

e spanish.Name Nombre} 
english: 


english.$word)" 


Ist { 


tch $1 $lang]} { 
p $lang.$w $word 


State $lookup 
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} 
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{HERA ABA AA AAA AAAAAAAAAAAAAABAAAAE 


iF 


iF 


proc insert {parent args}-- 
Insert a new Label/Entry pair 
Arguments 
-width Width of entry widget 
-alternates List of language alternates: 
{langl wordl lang2 word2} 
-text Text for label 
-textvar Textvariable for entry widget 
Results 
Adds new label/entry pair and increments the row pointer. 


proc insert {parent args} { 


} 


variable worldFormState 

set width 10 

incr worldFormState($parent. row) 
set alternates " " 


foreach {key val} $args { 
set varName [string range $key 1 end] 
set $varName $val 

} 


set w Lentry $parent.eLunique] -textvariable $textvariable \ 
-width $width] 


grid $w -row $worldFormState($parent.row) -column 1 
set w Llabel $parent.][unique] -text $text] 

grid $w -row $worldFormState($parent.row) -column 0 
updateXlateTable $alternates 


{HERA ABA AA AAA AAAAAAAAAAAAAAAAAAE 


proc WorldFormProc {widgetName subCommand args} 

The master procedure for handling this megawidget’s 
subcommands 
Arguments 

widgetName The name of the worldForm widget 
subCommand The subCommand for this cmd 

args: The rest of the command line 

arguments 
Default subCommands are: 
configure - configure the parent frame 


widgetconfigure - configure or query a subwidget. 
mega widgetconfigure itemID -key value 
mega widgetconfigure itemID -key 
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i## widgetcget - get the configuration of a widget 


if mega widgetcget itemID -key 
## widgetcommand - perform a command on a widget 
+ mega widgetcommand itemID commandString 
if names - return the name or names that match 

if a pattern 

if mega names i## Get names of all widgets 
i mega names *ax ## Get names of widgets 

tf dt with an ‘a’ in them. 

if subwidget - return the full pathname of a 

if requested subwidget 

# Results 


# Evaluates a subcommand and returns a result if required. 


proc WorldFormProc {widgetName subCommand args} { 
variable worldFormState 
set cmdArgs $args 
switch -- $subCommand { 
configure { 
return [eval $widgetName.fr configure $cmdArgs ] 


widgetconfigure { 
set sbwid [lindex $cmdArgs 0] 


set cmd [lrange $cmdArgs 1 end] 
set index $widgetName.subWidgetName.$sbwid 


catch {eval $worldFormState($index) configure $cmd} rtn 
return $rtn 


return [eval insert $widgetName $cmdArgs ] 


widgetcget { 
if {Lllength $cmdArgs] != 2} { 
error "$widgetName cget subWidgetName -option" 
} 
set sbwid [lindex $cmdArgs 0] 
set index $widgetName.subWidgetName.$sbwid 
set cmd [lrange $cmdArgs 1 end] 
catch {eval $worldFormState($index) cget $cmd} rtn 
return $rtn 


532 CHAPTER 14 Tk Megawidgets 


widgetcommand { 
return [eval DoWidgetCommand $widgetName $cmdArgs] 
} 


names { 
if {{string match $cmdArgs ""]} { 
set pattern $widgetName.subWidgetName.x* 
} else { 
set pattern $widgetName.subWidgetName.$cmdArgs 
} 
foreach n [array names worldFormState $pattern] { 
foreach {td ws name} [split $n .] {} 
lappend names $name 
} 
return $names 
} 


subwidget { 
set name [lindex $cmdArgs 0] 
set index $widgetName.subWidgetName. $name 
if {Linfo exists worldFormState($index)]} { 
return $worldFormState($index ) 


} 

default { 
error "bad command" "Invalid Command: $subCommand \n\ 
must be configure, widgetconfigure, widgetcget, names,\ 
insert, or subwidget" 


Script Example 
source Chl4-World.tcl 


grid LworldForm .x] 


.xX insert -text Name -textvariable name \ 
-alternates {english Name french Nom \ 
spanish Nombre german Name} 


.xX insert -text Address -textvariable address -width 20 \ 
-alternates {english Address french Adresse \ 
spanish Direccin_ german Adresse} 
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Script Output 


translate translate 


Name Nom 
Address Adresse 


translate Spanish — translate Spanish —| 


Nom Nombre 
Adresse Direccion 


INCORPORATING A MEGAWIDGET INTO A LARGER MEGAWIDGET 


The Tk design philosophy is that large complex things can be built out of smaller, less complex things. 
A megawidget is larger than a primitive widget, but it should still be possible to merge one or more 
megawidgets into a larger megawidget. 

In this section, we will create a larger megawidget that contains two of the scrol1edLB widgets, a 
label,a button, and an entry widget. This megawidget will allow a user to define a filter to extract a 
subset of the entries from the first listbox for display in the second listbox. When the widget is queried, 
it will return the selected items in the filtered listbox, or in the selected items in the unfiltered listbox if 
nothing was selected in the filtered box. 

The justification for this widget is that sometimes there are too many items in a listbox to find those 
the user is interested in, but a simple filter could cut down the size to something manageable. This is 
similar to the effect that various file browsers get with the “filter” option, but this widget allows the 
user to see both the unfiltered list and the filtered list at the same time. 

Like the scrolledLB, this megawidget is implemented as a procedure for creating the widget 
in the global scope with support procedures maintained in a namespace scope. As described in the 
previous section, there are some points to watch when using namespaces with Tk widgets. The button 
command string uses the namespace code command to cause the script to be evaluated in the current 
namespace. 

If we knew that the fi]teredLB widget would always be defined at a top-level, we could just 
define the command string as :: fil teredLB::DoFilter, but just as the scrol ledLB megawidget 
is contained within the filteredLB widget, the filteredLB widget may be contained in a larger 
widget, as shown in the file browser megawidget example in the next section. 
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_———_—A 
Example 15 
Complete Code 

it Name: Filtered.tcl 

lappend auto_path . 

package provide filteredLB 1.0 

package require scrolledLB 


JHA ABABA AAA AAA AAA AAA AAA AE 
## proc filteredLB {args} 


i## Create a filteredLB megawidget 

i## External entry point for creating a megawidget. 

if Arguments 

if args A list of arguments to define the widget. 
if f the first argument starts with a "." 
if it will be used as the name of the main frame. 
if If this is not provided, the megawidget 

i is a child of the root frame ("."). 

i## Results 

i## Creates a procedure with the megawidget name for 
if processing widget commands 

if Returns the name of the megawidget 

proc filteredLB {args} { 


set newWidget [eval filteredLB::MakefilteredLB $args] 


set newCmd [format treturn [namespace eval %s %S %S $args ]}\ 
filteredLB FilteredLBProc $newWidget ] 


proc $newWidget {args} $newCmd 


return $newWidget 

} 

namespace eval filteredLB { 
variable filteredLBState 


i## Assign a couple defaults 
set filteredLBState(unique) 0 


MMMM CG Ciiiiiiiiiiiciinainaaaaaiaaaaa 
## proc MakefilteredLB {args} 

it Create a filteredLB megawidget 

if Arguments 
# args A list of arguments to define the widget. 

if If the first argument starts with a "." 

if it will be used as the name of the main frame. 
if If this is not provided, the megawidget 
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is a child of the root frame 


ae) 


535 


Subsequent args are -option/value pairs. 
?-scrollposition left/right? 
The side of the listbox for the scrollbar 


if Results 
Returns the name of the parent frame for use as a 


# 
# 


meg 


awidget 


proc MakefilteredLB {args} { 
variable filteredLBState 


if Se 


t the default 


name 


set holder .filteredLB_$filteredLBState(uni que) 


incr 


filteredLBS 


tate(uni que) 


# If the first argument is a window path, use that as 


# th 
if 


sev 
sev 


sev 
sev 
sev 
SOL 
sev 
sev 
sev 
sev 
sev 
sev 
se 
sev 


fore 


sev 


if 


e base name 


args Llrep 


d 1 

Wi 
LBS 
BSt 
BS 
BSt 


t Comman 
ight an 
tered 
tered 
tered 
tered 
tered 
tered 
tered 
tered 
tered 
tered 
tered 
tered 


LBSt 
LBSt 
BSt 
BS 
BSt 
LBSt 
LBSt 
BSt 


ach {key va 
keyName [s 
{!Linfo ex 


[string first 
holder [Llindex $args 0] 


ee] 


ee 


a 
a 
a 
a 
Xe] 
a 
a 
a 
a 


ace $args 0 


WwW 


0] 


fau 
bie 
hei 
id 


n 


+ WN 


tleText) 
tternVariab 
tternWidth) 


for this widget. 
[lindex $args 0]] == 0} { 


ts here, 
S 
ght) 5 

th) 20 

tboxlHeight 
elText) ti 
tboxlWidth) 
tbox2Height 
e2Text) ti 
tbox2Width) 
eFont) {he 
Cit 


$key 1 end] 


) 10 

tlel 

30 

) 10 

tle2 

30 

vetica 20 bold} 
e 

e) filterVar 

0 


filteredLBState($holder.$keyName)]} { 


regsub -all 


[array names filteredLBState $holder.*] \ 


okLi 
error "Bad o 


ine option de 
dth are free 
te($holder. 
ate($holder 
te($holder. 
te($holder. 
te($holder. 
te($holder. 
te($holder. 
te($holder. 
te($holder. 
te($holder 
te($holder. 
te($holder. 
} $args { 
tring range 
ists \ 
"$holder." \ 
st 


ption" \ 


"Invalid option ’$key’.\n\ 
Must be one of $okList" 
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} 
set filteredLBState($holder.$keyName) $val 


} 


if Create master Frame 

frame $holder -height $filteredLBState($holder.height) \ 
-width $filteredLBState($holder.width) \ 
-class FilteredLB 


i## Apply invocation options to the master frame, as appropriate 
foreach {opt val} $args { 
catch {$holder configure $opt $val} 
} 
Draw $holder 


if We can’t have two widgets with the same name. 
if Rename the base frame procedure for this 

i## widget to $holder.fr so that we can use 

it $holder as the widget procedure name 

if for the megawidget. 
uplevel #0 rename $holder $holder.fr 


if When this window is destroyed, 
i## destroy the associated command. 
bind $holder <Destroy> "+ rename $holder {}" 


return $holder 
} 


Mae 
i## proc Draw {parent}-- 

if creates the subwidgets and maps them into the parent 

if Arguments 

i## parent The parent frame for these widgets 

fl 
it Results 
it New windows are created and mapped. 
proc Draw {parent} { 
ariable filteredLBState 
age create photo arrow -data { 

01GOD1 hEAAQAPABAAAAAP/ // yH5BAAAAAAALAAAAAAQABAAAAK 
TJgwY cKECRMmTJgwY cKECRMmT J gwY cKECBMmTJgwY cKEABMmT J 
wY CKEABEmTJgwY cKEAAEmDAgQTECAAAEi DAGQIECAAAECDAGQI 
CAAAE1 TUgwY cKEAAEmTUgwY cCKEABEmTJgwY CKEABMmTJgwY cKE 
CBMmTJUgwY cKECRMmTJgwY cCKECRMmT JU gwY CKECRMmBQA7 

} 


maQannn-< 


} 


14.7 Incorporating a Megawidget into a Larger Megawidget 537 


set w [scrolledLB 
-listboxHeight 
-titleText $fi 
-listboxWidth 


set filteredLBStat 
grid $w -row 2 -c 


set w [scrolledLB 
-listboxHeight 
-titleText $fi 
-listboxWidth 
set filteredLBStat 
grid $w -row 2 -c 


set w [label $pare 
-font $filtere 
-text $filtere 
set filteredLBStat 
grid $w -row 0 -c 


set w Lentry $pare 
-textvar $filt 
-width $filter 
set filteredLBStat 
grid $w -row -C 


set w [button $par 
-jmage arrow \ 
-command "[nam 
set filteredLBStat 
grid $w -row 2 -c 


$parent.listl \ 
filteredLBState($parent.listboxlHeight) \ 
lteredLBState($parent.titlelText) \ 
$filteredLBState($parent.listboxlWidth) ] 


e($parent.subWidgetName.listl) $w 
olumn 0 -rowspan 2 


$parent.list2 \ 
filteredLBState($parent.listbox2Height) \ 
lteredLBState($parent.title2Text) \ 
$filteredLBState($parent.listbox2Width) ] 
e($parent.subWidgetName.list2) $w 

olumn 2 -rowspan 2 


nt.title \ 
dLBState($parent.titleFont) \ 
dLBState($parent.titleText) ] 
e($parent.subWidgetName.title) $w 
olumn 0 -columnspan 3 


nt.pattern \ 
eredLBState($parent.patternVariable) \ 
edLBState($parent.patternWidth) ] 
e($parent.subWidgetName.pattern) $w 
olumn 0 -columnspan 3 


ent.go \ 


espace code [list DoFilter $parent]]"] 
e($parent.subWidgetName.go) $w 
olumn 1 -sticky n 


{HABER AAA ABA AAA AAA AAA AAA AAA 


# 


# 
iF 
iF 
iF 
# 
# 


proc DoWidgetCommand 


proc DoWidgetCom 
Perform operations 
Arguments 
widgetName: The n 


widgets: A list 
cmd: A co 
Results 


Does stuff about 


variable filteredL 
foreach widget $wi 
set index $widge 


and {widgetName widgets cmd}-- 
on subwidgets 


ame of the holder frame 
of the public names for subwidgets 
and to evaluate on each of these widgets 


the subwidgets 

{widgetName widgets cmd} { 
BState 

dgets { 
tName.subWidgetName. $widget 
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} 
} 


eval $filteredLBState($index) $cmd 


{HERA ABABA AAA AAA AAA 


dt op 
if Te 
oa 


df Ar 
oh 


if Re 
dee Th 
proc 

Va 


se 
se 


se 


fo 


} 
} 


roc DoFilter {holder}-- 
sts items in full listbox, and puts ones that match 
pattern into the second listbox. 


guments 
older The name of the parent frame. 


sults 

he second listbox (list2) may receive new entries. 
DoFilter {holder} { 

riable filteredLBState 


t pattern [$filteredLBState($holder.subWidgetName.pattern) get] 
t fullListbox [[$holder subwidget listl] subwidget list] 
t filterListbox [[$holder subwidget list2] subwidget list] 


reach item [$fullListbox get 0 end] { 
if {{Lstring match $pattern $item]} { 
$filterListbox insert end $item 


} 


ii 


dt op 

if Re 

dt 

df Ar 

oh 

dt 

if Re 

ON 

proc 
se 
se 
se 
fo 


} 
if 


roc Selection {holder}-- 
turns the selected items from the second listbox 


guments 
older The name of the parent frame. 


sults 

o changes to widget 

Selection {holder} { 

t filterListbox [[$holder subwidget list2] subwidget list] 
t lst [$filterListbox curselection] 

t itemlst "" 
reach $lst { 
lappend itemlst [$filterListbox get $1] 


{Lstring match $itemlst ""]} { 
set fullListbox [[$holder subwidget listl] subwidget list] 
set Ist [$fullListbox curselection] 


} 
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set itemlst "" 
foreach 1 $lst { 
lappend itemlst [$fullListbox get $1] 
} 
} 
return $itemlst 


{HEAR AEA AAA AA AAA AAA AAA AAA AAA 


iF 
i 
iF 
# 
# 
# 
iF 
iF 
# 
# 
# 
iF 
iF 
iF 
# 
# 
# 
iF 
iF 
iF 
# 
# 
# 


proc FilteredLBProc {widgetName subCommand args} 
The master procedure for handling this megawidget’s 
subcommands 
Arguments 
widgetName: The name of the filteredLB 
widget 
subCommand The subCommand for this cmd 
args: The rest of the command line 
arguments 
Default subCommands are: 
configure - configure the parent frame 


widgetconfigure - configure or query a subwidget. 

a widgetconfigure itemID -key value 

a widgetconfigure itemID -key 

widgetcget - get the configuration of a widget 

ega widgetcget itemID -key 

widgetcommand - perform a command on a widget 

ega widgetcommand itemID commandString 

names - return the name or names that match 

pattern 

ega names # Get names of all widgets 

ga names xa* # Get names of widgets 
with an ‘a’ in them. 

subwidget - return the full pathname of a 
requested subwidget 

Results 

Evaluates a subcommand and returns a result if required. 


proc FilteredLBProc {widgetName subCommand args} { 


variable filteredLBState 
set cmdArgs $args 
switch -- $subCommand { 


configure { 
return [eval $widgetName.fr configure $cmdArgs ] 
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widgetconfigure { 

set sbwid Llindex $cmdArgs 0] 

set cmd [lrange $cmdArgs 1 end] 

set index $widgetName.subWidgetName.$sbwid 

catch {eval \ 
$filteredLBState($index) configure $cmd}  rtn 
return $rtn 


delete - 
insert { 
return [eval $widgetName.listl $subCommand $cmdArgs ] 


selection {return [Selection $widgetName]} 


widgetcget { 
if {Lllength $cmdArgs] != 2} { 
error "$widgetName cget subWidgetName -option" 
} 
set sbwid Llindex $cmdArgs 0] 
set index $widgetName.subWidgetName.$sbwid 
set cmd [lrange $cmdArgs 1 end] 
catch {eval \ 
$filteredLBState($index) \ 
cget $cmd} rtn 
return $rtn 


widgetcommand { 
return [eval DoWidgetCommand $widgetName $cmdArgs ] 


} 


names { 
if {L[string match $cmdArgs ""]} { 

set pattern $widgetName.subWidgetName.x* 

} else { 

set pattern $widgetName.subWidgetName.$cmdArgs 

} 


foreach n [array names filteredLBState $pattern] { 
foreach {d ws name} [split $n .] {} 
lappend names $name 

} 

return $names 
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subwidget { 
set name [lindex $cmdArgs 0] 


set index $widgetName.subWidgetName. $name 
if {Linfo exists filteredLBState($index)]} 


return $filteredLBState($index) 


default { 

error "bad command" "Invalid Command: 
$subCommand \n \ 
must be configure, widgetconfigure, 
widgetcget, names, \ 
delete, insert, selection, \ 
or subwidget" 


\ 


\ 


{ 


Using the fi1teredLB for the file browser is simple. You simply create the megawidget, map it, 


and fill it with the appropriate values, as shown in the following example. 


Note the option add commands. These set widgets associated with the filteredLB widget to 
a medium gray, and widgets associated with the scrol]ledLB widget to a lighter gray. The option 
command will apply colors to the most specific option. The parts of the filteredLB widget that are 
implemented with the scrolledLB widget override the darker gray to become lighter, whereas the 
title, entry, and button widgets that are not part of a scrolledLB widget are assigned the 
medium gray color. 


—_——— ee OO 
Example 16 


Script Example 


lappe 


d auto_path. 


package require filteredLB 


optio 
optio 


set fb LfilteredLB .dir -patternVariable tst 
-titlelText "Original Data" -title2Text "Filtered Data" 
-listboxlHeight 5 -listbox2Height 5 \ 
-titleText "Filtered directory contents" 
-listboxlWidth 15 -listbox2Width 15] 


add «FilteredLB*Background #ddd 
add *ScrolledLB*Background #feee 


\ 


\ 


\ 
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grid $fb 
set path /bin 


foreach f [lsort [glob $path/x«]] { 
$fb insert end $f 
} 


button .report -text "Report" \ 


-command {tk_messageBox -type ok -message [.dir selection]} 
grid .report 


Script Output 


iltered directory contents 


Original Data > Filtered Data 


Jbin/arch Jbin/sh 


/bin/basename bin/tesh 
Jbin/bash bin/wish 
Jbin/cat , sbin/zsh 


/bin/awk fish 


Report | 


14.8 MAKING A MODAL MEGAWIDGET: THE grab AND tkwait 
COMMANDS 


In this section we will take the fi 1 teredList megawidget we just developed and make a modal file 
selection widget. This widget is far from the last word in file selection widgets, but it makes a good 
example of how a modal widget can be constructed. 

This widget is implemented as a single procedure that creates and displays the megawidget and 
returns the results of the user interaction when that interaction is complete. The condition for comple- 
tion is that the user has either clicked the Quit button, clicked the OK button, or destroyed the widget 
using a window manager command. 

This widget introduces the grab and tkwait commands that have not been used in previous exam- 
ples. The grab command allows your application to examine and control how mouse and keyboard 
events are reported to the windows on your display. The t kwait command will cause a script to pause 
until an external event (such as a window being destroyed) occurs. 
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14.8.1 The grab Command 

By default, whenever a cursor enters or leaves a widget, an Enter or Leave event is generated. When 
the cursor enters a widget, that widget is said to have focus, and all keystroke and button events will 
be reported to that widget. By using the grab command, you can declare that all keyboard and mouse 
events will go to a particular widget regardless of the location of the cursor. This requires a user to 
perform a set of interactions before your program releases the grab. Once the grab is released, the 
focus will follow the cursor and mouse and keyboard events will be distributed normally. 

The grab command has several subcommands that let you determine whether other grabs are 
already in place (in which case your program should save that state and restore it when it is done) 
and set a new state. You can learn what window is currently grabbing events with the grab current 
command. 


Syntax: grab current ?window? 
Returns a list of the windows that are currently grabbing events. 
window If window is defined and a child of window has grabbed events, that child 
will be returned. If no child of the window has grabbed events, an empty 
string is returned. If window is not defined, all windows in the application 
that have grabbed events will be reported. 


A window can either grab all events for that application or all events for the entire system. The 
default mode is to grab only events for the current application. If you need to grab events for the entire 
system, this can be done with the - global flag when a grab is requested. If a grab is in effect, you 
can determine whether it is for a local (default) or global scope with the grab status command. 

Use care when using grab global. When your application grabs all events the rest of the 
windowing system is frozen until your application releases the grab global. 

The following example shows the focus being grabbed by a label, instead of the button. Since the 
label is grabbing focus, the button never responds to <Enter> or button events. 


Example 17 
Script Example 
grid [button .b -text "Show" \ 

-command {puts [grab current]}] 
grid [label .1 -text "holding focus"] 
grab .1 
puts "Focus is held by: [grab current ]" 


Script Output 


Show | 


olding focus 


Focus is held by: .1 
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Syntax: grab status window 
Returns the status of a grab on the defined window. The return will be one of: 


local The window is in local (default) mode. Only events 
destined for this application will be routed to this 
window. 

global The window is in global mode. All events in the 


system will be routed to this window. 
empty string There is no grab in effect for this window. 
window The window for which status will be returned. 


Example 18 
Script Example 
pack [button .b -text "Show" -command {puts [grab current]}] 
pack [label .1 -text "holding focus" ] 
grab .] 
puts "Status for .1 is: [grab status .1]" 


Script Output 


Status for .1 is: local 


| 
You can declare that all events will go to a window with the grab or grab set command. These 
commands behave identically. 
Syntax: grab ?set? ?-global? window 
Set a window to grab keyboard and mouse events. 


-global Grab all events for the system. By default, only events generated while 
this application has the focus will be directed to this window. 


window — The window to receive the events. 


14.8.2 The tkwait Command 


Once all events in the system are directed to the modal widget, the widget has to know when the inter- 
action is complete. We can force the Tcl interpreter to wait until the user has performed an interaction 
with the tkwait command. This command will wait until a particular event has occurred. The event 
may be a variable being modified (perhaps by a button press), a change in the visibility of a window, 
or a window being destroyed. 
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Syntax: tkwait EventType name 
Wait for an event to occur. 
EventType A name describing the type of event that may occur. 
The content of name depends on which type of event 
has occurred. 


Valid events are: 


variable varName Causes tkwait to wait until the variable varName 
changes value. 


visibility windowName Causes tkwait to wait until the window windowName 
either becomes visible or is hidden. 


window windowName Causes tkwait to wait until the window named in 
windowName is destroyed. 


——— ee eee 
Example 19 


Script Example 


i## Create and display two widgets} 
grid [label .1 -text "I’m the first .1"] 
grid [button .b -text "Click to destroy label" -command "destroy .1"] 


i## The code pauses here until the window named .1 is destroyed 
## This will happen when the button is clicked. 
tkwait window .1 


if After the button is clicked, and .1 is destroyed, 
i# = anew .1 is created and packed. 
grid [label .1 -text "I’m a new .1"] 


Script Output 
Before clicking button 


I'm the first . 


Click to destroy label 


I'm a new .!| 


3 The Modal Widget Code 


The next example shows how the filtered 1istbox megawidget can be used to create a modal file 
selection megawidget. 
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_.——_AA 
Example 20 
Complete Code 

dH Name: getFileList.tcl 

lappend auto_path "." 

package require filteredLB 

package provide fileSel 1.0 


JHA AAA AA AAA AAA AAA AAA AA AAA AAA AAA AAA 
## proc getFileList {directory}-/- 

if Returns a list of selected files from the requested 

if directory. 

if Arguments 


if directory The directory to return a list of files from 
i 

i## =Results 

if Creates a new window and grabs focus until user 

if interacts with it. 


i## Returns a list of the selected files. 
i## =©=Returns an empty list if: 


if no files are selected, 
dt ‘QUIT’ button is clicked 
dt window is destroyed. 


proc getFileList {directory} { 
global popupStateVar 


i## Find an unused, unique name for a toplevel window. 

## winfo children returns a list of child windows. 

set unique 0 

set childlist [winfo children .] 

while {£lsearch childlist .dirList_$unique]!= -1} { 
incr unique 

} 


i## Create the new toplevel window that will hold this 
if widget 
set win [toplevel .dirList_$unique -class Fileselector] 


i## Create the widget as a child of the $win window 
i## And configure the listboxes for multiple selections 
set fl [filteredLB $win.fll -titleText "Select Files" \ 
-titlelText "Files in Directory" \ 
-title2Text "Filtered list" ] 


[$fl subwidget listl] \ 
widgetconfigure list -selectmode multiple 


[$f 


it 
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1 subwidget 


list2] \ 


widgetconfigure list -selectmode multiple 


And fill the 


full list 


foreach file [lsort [glob -nocomplain $directory/*]] { 
fl insert end [file tail $file] 


$ 
} 


it 
iF 


pac 


# 


set 


set 


set 


pac 
pac 
pac 


i 
iF 
iF 


Pack the fil 
new window 
k $f1 -side 


teredList megawidget at the top of the 


COD 


Create the buttons in a frame of their own, and pack them 


bframe [fra 


{set popupS 


ok [button 


e $win. buttons ] 


quit [button $bframe.quit -text "QUIT" -command\ 


tateVar(ret) ""}] 


bframe.ok -text "OK" -command \ 


"set popupStateVar(ret) \[$fl selection\]"] 


$ok -side 
$bframe -s 


$quit -side left 


left 
ide bottom 


bind the destroy event to setting the trigger variable, 
so we can exit properly if the window is destroyed by 
the window manager. 


bind $win <Destroy> {set popupStateVar(ret) ""} 


# 
it 


set oldFocus [focus] 


tk library. 


popupStatevVa 


hen the use 


The following code is adapted from dialog.tcl in the 


It sets the focus of the window manager 


on the new window, and waits for the value of 


r(ret) to change. 


r clicks a button, or destroys the window, 


it will set the value of popupStateVar(ret)!, 


and processing will continue 


Set a grab and claim the focus. 


set oldGrab [grab current $win] 
{$oldGrab != ""} { 
set grabStatus [grab status $oldGrab] 


Vt 


} 
gra 
foc 


b $win 
us $win 
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i## Wait for the user to respond, then restore the focus 

i## and return the index of the selected button. Restore 

if the focus before deleting the window, since otherwise 
if the window manager may take the focus away so we can’t 
## redirect it. Finally, restore any grab that was in 

i## effect. 
tkwait variable popupStateVar(ret) 
catch {focus $o0ldFocus} 


## It’s possible that the window has already been 
i## destroyed, hence this "catch". Delete the 
i## <Destroy> handler so that popupStateVar(ret) 
if doesn’t get reset by it. 
catch { 
bind $win <Destroy> {} 
destroy $win 
} 


if {$oldGrab != ""} { 
if {$grabStatus == "global"} { 
grab -global $o0ldGrab 
} else { 


grab $oldGrab 
} 
} 
return $popupStateVar(ret) 


Script Example 
i## The widgets pkgIndex.tcl file is in the current directory 
i## in this example. 
lappend auto_path "." 


i## Include the widgets package to get the 
it fileSel megawidget. 
package require fileSel 


i## Create a label and entry widget to get a base directory path 
set dirFrame [frame .fl] 

label $dirFrame. -text "base directory: " 

entry $dirFrame.el -textvariable directory 


it Create buttons to invoke the getFileList widget. 

set buttonFrame [frame .f2] 

button $buttonFrame.bl -text "Select Files" \ 
-command {set filelist [getFileList $directory]} 
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i## The selected files will be displayed in a label widget 
if with the -textvariable defined as the filelist returned 
if from the getFileList widget. 
set selFrame [frame .sel] 
set selectLabel [label $selFrame.label -text \ 

"Selected files:"] 
set selectVa essage $selFrame.selected \ 
-textvariable filelist -width 100] 


=i 


i## and pack everything 

pac dirFrame.11 -side left 
pac dirFrame.el -side right 
pac dirFrame -side top 

pac buttonFrame -side top 

pac buttonFrame.bl -side left 
pac selFrame -side top 

pac selectVal -side right 

pac selectLabel -side left 


Script Output 
Initial Window 


pase directory 
Select Files 


Selected files: 


Select Files 


*sh 
Files in Directory => Filtered list 


Select Files =e 


Selected files: tclsh wish 
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) AUTOMATING MEGAWIDGET CONSTRUCTION 


You may have noticed that the three megawidgets presented in this chapter are very similar. In fact, 
the bulk of the code in these widgets is identical. Building custom megawidgets can be automated in a 
few ways, by working from a skeleton and filling in the pieces, by further automating building from a 
skeleton with a configuration file and a Tcl script, or by assembling compound widgets on the fly with 
another set of procedures. 


14. Building Namespace Megawidgets Summary 


The architecture of these megawidgets is consistent. There is a procedure in the global scope to create 
a megawidget, which calls procedures in the appropriate namespace to populate the megawidget and 
return the name of the procedure to interact with the megawidget. A second global scope procedure is 
created to interact with the megawidget. This procedure has the same name as the parent frame, and 
will evaluate scripts within the megawidget namespace to implement the widget commands. 

The unique part of each megawidget is the procedure to draw the subwidgets, and the procedures 
that implement unique subwidget commands. 

There are many ways to construct a compound widget using classic Tk widgets and namespaces. A 
compound widget can be built from a skeleton, the widgets can be created from a configuration file, or 
generated by a set of scripts. 

Jeffrey Hobbs, jeff@ hobbs.org, created a technique for automating megawidget creation with his 
widget package. His package will allow you to easily create a megawidget that uses a subwidget 
command or a naming convention to access the subwidgets. The subwidgets can be configured by 
accessing them as individual widgets, using either the name returned with the subwidget command 
or the subwidget naming convention to access the subwidgets. Configuration options related to the 
entire megawidget can be processed via the megawidget widget procedure, a procedure with the same 
name as that given to the megawidget. 


[A | 


14.10 BUILDING MEGAWIDGETS WITH TCLOO 


Building megawidgets with namespaces is the traditional approach to compound and complex wid- 
gets. However, building megawidgets involves concepts like inheriting behavior and aggregating 
multiple objects into a single entity. These requirements are what object-oriented design styles are 
best at. 

TclOO supports building megawidgets. Many of the design decisions are the same, whether you 
are building a megawidget in a namespace or as an TclOO class. Decisions like whether the widget 
should be modal or not, whether it should create a toplevel widget or be embedded in the applications 
window, whether it should mimic Tk behavior or follow its own patterns, etc. All of these patterns can 
be implemented with TclOO as easily or easier than with namespaces. TclOO even has features that 
make it easier to mimic the behavior of the Tk widgets. 

As with building compound widgets using namespaces, there are a few different patterns that can 
be used to build TclOO megawidgets. 
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14.10.1 Using a Wrapper Proc for TclO0-Based Widgets 


The simplest pattern is similar to the pattern used for namespace-based compound widgets—a global 
procedure as a wrapper to create a megawidget, perform the renaming and return a new widget 
command with the appropriate name. 


The next example shows a scrolled listbox widget built using a factory procedure scro11edLB. The 


scrolledLB proc creates a compound widget using TclOO instead of in a namespace. The differences 
to look for are: 


1. 
2. 


The scrol1edLB command creates a new object, rather than calling a command in a namespace. 
With TclOO the State variable is specific to each object, rather than being shared by all widgets 
using this namespace. Because each object has a private copy of State there is no need to include 
the widget name as part of the State array indices. This makes the references simpler. 


. Instead of a single scrol1edLBProc with a switch statement to determine which widget command 


to evaluate, each subcommand is a method in the scrol1edLB class. 


. When the widget is destroyed, the binding destroys the object, instead of renaming the proc to an 


empty string. 


. Subwidget options are identified as subwidgetName.optionName. For example, the height of the 


listbox is ]ist.height. 


OOOO —-.:—nmnmn— OO ay» 
Example 21 


Script Example 


package provide scrolledLB 2.0 


JHA HBA AAA AAR AAA AAA AAA AAA AAA AA AAA AAA AAA AA AAA AAA AAA 
## proc scrolledLB {args} 

if Create a scrolledLB megawidget 

i## External entry point for creating a megawidget. 

df Arguments 

i## = ?parentFrame? A frame to use for the parent, 


if If this is not provided, the megawidget 

if is a child of the root frame ("."). 

dt 

if args A set of key/value pairs to describe the listbox 
df 

if Results 


## Creates a procedure with the megawidget name for processing 
if widget commands 

if Returns the name of the megawidget 

proc scrolledLB {winName args} { 


set newWidget [scrolledLB_OO new $winName {x*}$args] 


if Define a new command which passes control to the 
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if scrolledLB::scrolledLBProc command and return the results. 
rename $newWidget "“$winName" 


return $winName 
} 


o00::class create scrolledLB_OO { 
variable State 


HMMM i iiiiiMiiicaiiainadaaaiaaaaa 
if method constructor 

it Create a scrolledLB megawidget 
if Arguments 
i## frameName A frame to use for the parent. 


if Subsequent arguments are -option/value pairs 

it =2-scrollSide left/right? 

if The column in the scrolledLB for the scrollbar 
i## Results 


i## Returns the name of the parent frame for use as a 
it ~=megawidget 


constructor {frameName args} { 


4 Set Command line option defaults here 
if height and width are freebies 
array set State { 

height 5 

width 20 

list.background white 

list.height 10 

list.width 20 

scroll.side 1 

list.side 0 

title.text title 
} 


foreach {key val } $args { 
set keyName [string range $key 1 end] 
if {!Linfo exists State($keyName)]} { 
error "Bad option" \ 
"Invalid option *$key’.\n\ 
Must be one of [array names State]" 
} 
set State($keyName) $val 
} 


} 


Ti 


# 
# 
# 
iF 
i 
iF 
# 
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i## Create master Frame 

frame $frameName -height $State(height) \ 
-width $State(width) \ 
-class ScrolledLB 


i# Apply invocation options to the master frame, as appropriate 


foreach {opt val} $args { 
catch {$frameName configure $opt $val} 
} 


my Draw $frameName 


## Apply subwidget options 
foreach {k v} $args { 
lassign [split $k .] sub opt 
set sub [string trim $sub -] 
my widgetconfigure $sub -$opt $v 


i## We can’t have two widgets with the same name. 
if Rename the base frame procedure for this 

i## widget to $frameName.fr so that we can use 
it $frameName as the widget procedure name 

if for the megawidget. 


uplevel #0 rename $frameName $frameName.fr 
set State(subWidgetName.frame) $frameName.fr 


i When this window is destroyed, 

if destroy the associated command. 

bind $frameName <Destroy> "+ [self] destroy" 
return $frameName 


method Draw {parent}-- 


creates the subwidgets and maps them into the parent 
Arguments 

parent The parent frame for these widgets 

Results 

New windows are created and mapped. 


method Draw {parent} { 


variable State 


set tmp [scrollbar $parent.yscroll -orient vertical \ 


-command "$parent.list yview" ] 
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set State(subWidgetName.yscroll) $tmp 
grid $tmp -row 1 -sticky ns \ 
-column $State(scroll.side) 


set tmp [listbox $parent.list  \ 
-yscrollcommand "$parent.yscroll set" \ 
-height $State(list.height)\ 
-width $State(list.width) ] 


set State(subWidgetName.list) $tmp 
grid $tmp -row 1 -column $State(list.side) 


set tmp [label $parent.title \ 
-text $State(title.text) ] 


set State(subWidgetName.title) $tmp 
grid $tmp -row 0 -column 0 -columnspan 2 
} 


iM Gg GS iiinainaaa aaa aaaa 
if method DoWidgetCommand {widgetName widgets cmd}-- 

i## Perform operations on subwidgets 

if Arguments 

if widgetName: The name of the holder frame 


if widgets: A list of the public names for subwidgets 

if =ocmd: A command to evaluate on each of these widgets 
fl 

if Results 


i## Does stuff about the subwidgets 


method DoWidgetCommand {widgetName widgets cmd} { 
variable State 
foreach widget $widgets { 
set index subWidgetName. $widget 
eval $State($index) $cmd 


} 


method selection {} { 
set Ist [$State(subWidgetName.list) curselection] 
set itemlst "" 
foreach 1 $lst { 
lappend itemlst [$State(subWidgetName.list) get $1] 
} 
return $itemlst 


method 


} 


method 


method 


method 


method 


method 


} 


method 
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configure {args} { 
return [eval $widgetName.fr configure ${*}$args] 


widgetconfigure {args} { 
set sbwid [lindex $args 0] 
set cmd [lrange $args 1 end] 
set index subWidgetName.$sbwid 
catch {eval \ 
$State($index) configure $cmd}  rtn 
return $rtn 


delete {args} 


return [eval $State(subWidgetName.list) delete {*}$args] 


insert {args} { 


return [eval $State(subWidgetName.list) insert {*}$args] 


widgetcget {args} { 
if {Lllength $args] != 2} { 

error "$widgetName cget subWidgetName -option" 
} 
set sbwid [lindex $args 0] 
set index subWidgetName.$sbwid 
set cmd [lrange $args 1 end] 


catch {$State($index) cget $cmd} rtn 
return $rtn 
} 


widgetcommand {args} { 
return [DoWidgetCommand $widgetName {x*}$args] 


names {args} { 

if {{string match $args ""]} { 
set pattern subWidgetName.« 

} else { 
set pattern subWidgetName.$args 

} 

foreach n [array names State $pattern] { 
foreach {w s name} [split $n .] {} 

lappend names $name 
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retur $names 


method subwidget {args} { 
set name [Llindex $args 0] 
set index subWidgetName. $name 
if {Linfo exists State($index)]} { 
return $State($index) 


} 

i## Example of use 

option add *ScrolledLB«xbackground #aaa 

set slb EscrolledLB .slb -list.background white -list.height 4 -scroll.side 2] 


$slb widgetconfigure title -font {arial 14 bold} -text "Files in /bin" 
puts "SLB: $slb" 


foreach file [lsort [glob /bin/x]] { 
slb insert end $file 

} 
grid .slb 


button .b -text "Print Selected" -command "puts \[$slb selection\]" 
grid .b 


Script Output 
Files in /bin 


Print Selected | 


/bin/wish 
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14.10.2 Using a Class Name as a Widget Type 
One issue with this solution is that the procedure creates an object for a class that does not have the 
same name as the factory method—the scro1l1edLB procedure creates a scrol 1edLB_00 object. 

The normal way to create a TclOO object is 
className create objectName ?args? 
or 
className new ?args? 
while the Tk widget create commands follow the pattern widgetType widgetName ?args? 

As you might expect, there is a technique to allow a TclOO className to be used like a Tk 
widgetType. The technique is overriding the unknown static method. 

Each TclOO class has a default method named unknown. The default method generates an error 
informing the user of acceptable commands: 


eee ee eee 
Example 22 
Script Example 


00::class create test { 
} 


test noSuchCommand 


Script Output 


unknown method "noSuchCommand": must be create, destroy or new 


You can override the unknown class as described in Section 10.6 by adding your own static 
unknown method. 

Section 10.6 explained that in order to add a class method, you need to define a classmethod 
procedure. A classmethod procedure looks like this: 


98} $$ 

Example 23 

Script Example 

proc ::00::define::classmethod {name {args ""} {body ""}} { 
i Create the method on the class if the caller gave 
# arguments and body 
if {Cllength [info level 0]] == 4} { 
uplevel 1 [list self method $name $args $body] 

} 
i Get the name of the class being defined 
set cls Llindex [info level -1] 1] 
if Make connection to private class "my 
# forwarding 


command by 
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uplevel forward $name Linfo object namespace $cls]::my $name 


The new unknown method will examine the arguments and determine whether the first argument 
starts with a period. If so, then the illegal method is an attempt to create a new object. The unknown 
method can create the new object and return the name or else pass control to the default unknown 
method with the next command. 

An unknown method will resemble this: 

classmethod unknown {w args} { 
if {Lstring match .* $w]} { 
[self] new $w {*}$args 
return $w 
} 
next $w {*}$args 
} 


As with other compound widget patterns, we need to rename the window procedure to a new name 
that will not conflict with the name of the new object. This is done in the constructor by renaming 
the widgetName to a new string and then using the se] f command within the constructor to rename 
itself to $widgetName. 

The critical part of the constructor looks like this: 

constructor {widgetName args} { 
set State(parent) [frame $widgetName -class labelEntry] 


rename ::$widgetName ::$widgetName. frame 
rename [self] ::$widgetName 


The next example shows a label/entry compound widget using this pattern. This widget has only a 
constructor and configure method. It uses a convention of identifying configuration options for the 
subwidgets as subwidgetName. option. To set the foreground of the label to black, the code would be 
$megawidget configure -label.foreground black 


:—_—<$£_—_§@ ——_— A. 


Example 24 
Script Example 
proc ::00::define::classmethod {name {args ""} {body ""}} { 


if Create the method on the class if the caller gave 
if arguments and body 
if {Cllength [info level 0]] == 4} { 

uplevel 1 [list self method $name $args $body] 
} 
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4 Get the name of the class being defined 

set cls [Llindex [info level -1] 1] 

## Make connection to private class "my" command by 

# forwarding 

uplevel forward $name Linfo object namespace $cls]::my $name 


00::class create labelEntry { 
variable State 
superclass oo::class 


classmethod unknown {w args} { 
if {Lstring match .* $w]} { 
[self] new $w {x}$args 
return $w 
} 
next $w {x}$args 
} 


constructor {widgetName args} { 


set State(parent) [frame $widgetName -class labelEntry] 


rename ::$widgetName ::$widgetName. frame 
rename [self] ::$widgetName 


i A label named label and an entry widget named entry. 
label $State(parent).label 
entry $State(parent).entry 


dt Grid the widgets in the frame 
grid $State(parent).label $State(parent).entry 


my configure {*}$args 


method configure {args} { 
i Step through the args and apply them as required. 
i "-entry.width" becomes "parent.entry configure -width" 


foreach {k v} $args { 

lassign [split $k .] type opt 

set type [string trim $type -] 

catch {$State(parent).$type configure -$opt $v} err 
} 


560 CHAPTER 14 Tk Megawidgets 


} 
i## A sample for using this compound widget. 


i## Create two labelEntry widgets. One for Author and one for Title 
labelEntry .title -label.text "Title: " \ 

-entry.textvariable State(title) -entry.width 23 
labelEntry .author -label.text "Author: " \ 

-entry.textvariable State(author) 


if Grid the widgets, author above title 
grid .author 
grid .title 


## Assign values to be displayed in the entry widgets. 
set State(title) "Tcl/Tk: A Developer’s Guide" 
set State(author) "Clif Flynt" 


if Reconfigure the author label to be invert video, to demonstrate 
if the configure method. 


.author configure -label.background black -label.foreground white 


Author: [iia 


ithe: Tel/Tk: A Developer's Guide 


14.1 Callbacks into Tcl00 Widgets 


When a Tk widget is created it creates the window and a command by the same name in the global 
scope. When a callback is invoked (as with a button click), this also happens in the global scope. In 
order to link a callback to an object’s method, we need to use the se] f command that was discussed 
in Section 10.5. 

The self command returns information about the call tree related to the current object. The most 
useful return value for a GUI programmer is that name of the current object. This name can be used to 
register a callback for a button, an after event, fileevent, etc. 

The my command also returns information about the current object. The my varname returns a 
fully qualified name that can be used as a textvariable ina Tk widget. 

The next example demonstrates how to build a TclOO class that creates a label that uses the object 
variable as a -textvariable, and a button that invokes an object method when clicked. 
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eee 
Example 25 
Script Example 


o00::class create OO_gui { 
variable objectVar 


constructor {} { 
set objectVar "no button clicked" 
label .1 -textvariable "[my varname objectVar]" 
button .b -text "Change label" -command "“[self] changeLabel" 
grid .1 
grid .b 
} 


method changeLabel {} { 
set objectVar "The button was clicked" 
} 
} 


OO_gui new 


Change label Change label 


14.10.4 Combining Tcl00 Compound Widgets 
Multiple TclOO-based megawidgets can be combined into larger compound widgets by simply creating 
the megawidgets the same way you would include standard Tk widgets. 

The next example demonstrates creating an entryForm widget using the previous labelEntry 
megawidget. Note that the - textvariab]e is defined using the my varname command and is passed 
to the |abelEntry object as the value for the -entry.textvariable option. 

The submit button uses the se] f command to invoke an object method. 


$A 


Example 26 
Script Example 
proc ::00::define::classmethod {name {args ""} {body ""}} { 


i Create the method on the class if the caller gave 
it arguments and body 


562 CHAPTER 14 Tk Megawidgets 


if {Cllength [info level 0]] == 4} { 

uplevel 1 [list self method $name $args $body] 
} 
dt Get the name of the class being defined 
set cls Llindex Linfo level -1] 1] 
i## Make connection to private class "my" command by 
if forwarding 
uplevel forward $name Linfo object namespace $cls]::my $name 


00::class create labelEntry { 
variable State 
superclass oo::class 


classmethod unknown {w args} { 
if {Lstring match .* $w]} { 
[self] new $w {x}$args 
return $w 
} 
next $w {x}$args 
} 


constructor {widgetName args} { 


set State(parent) [frame $widgetName -class labelEntry] 


rename ::$widgetName ::$widgetName. frame 
rename [self] ::$widgetName 


if A label named label and an entry widget named entry. 
label $State(parent).label 
entry $State(parent).entry 


dt Grid the widgets in the frame 
grid $State(parent).label $State(parent).entry 


my configure {*}$args 


method configure {args} { 
## Step through the args and apply them as required. 
# "-entry.width" becomes "parent.entry configure -width" 


foreach {k v} $args { 
lassign [split $k .] type opt 
set type [string trim $type -] 
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catch {$State(parent).$type configure -$opt $v} err 
} 


} 
00::class create entryForm { 


variable Values 


constructor { {parentFrame {}} } { 

set w LlabelEntry $parentFrame.name -label.text "Name: " \ 
-entry.textvariable [my varname Values(name)] -entry.width 15] 

grid $w 

set w LlabelEntry $parentFrame.email -label.text "Email: " \ 
-entry.textvariable [my varname Values(email)] -entry.width 15] 

grid $w 

set w LlabelEntry $parentFrame.passphrase -label.text "Passphrase: " \ 


-entry.textvariable [my varname Values(passphrase)] \ 
-entry.show * -entry.width 15] 
grid $w 


button $parentFrame.b -text "Submit" -command "[self] submit" 
grid $parentFrame.b 


} 


method submit {} { 
set msg "Name: $Values(name)\nEmail: $Values(email)\nSecret: $Values(passphrase)' 
tk_messageBox -type ok -message $msg 


} 


entryForm new 


Script Output 
Before clicking Submit button 


Name: John Smith 
Email: john@plymouth 


Name: John Smith 


Email: |john@plymouth Secret: Priscilla 


Submit 
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14.10.5 Adding New Functionality to a TclOO Widget 


Needing to change the functionality of a widget is almost as common as needing to put multiple widgets 
into a single compound widget. The TclOO-inheritance model supports adding new functionality to a 
TclOO-based widget and overriding behaviors you want to change. 

The superclass directive tells TclOO to inherit characteristics from another class and merge 
them into the current class. This lets you expand functionality by taking a previously designed class 
and adding new methods to it. 

Control can be passed from one class to another using the next command. This allows you to use 
functionality in the existing class’s methods while adding new functionality, or to completely replace 
one set of functionality with another. The next command can appear at any point in a method and 
will pass control to the method with the same name in a superclass. Look at the discussion of class 
hierarchies in Chapter 10 for more details on where the control may be placed. 

The next example adds a validation support to the ]abel Entry compound widget. The new class 
is named validatedLabelEntry. It uses the superclass command to inherit the ]abelEntry 
functionality of creating a label and entry widget, providing support for the conf i gure command and 
constructor. 

The validatedLabelEntry class requires a - validate option when it is created. The value for 
this option can be any value supported by the string is command. The string is command is 
used to validate the contents of the entry widget after each keystroke. 

There is no support for a - validate flag in the labelEntry class, so that option is tested and 
removed before the 1abel Entry constructor is invoked with next. Control returns to the val i- 
datedLabelEntry object after the label and entry widgets have been created. At this point, the 
validatedLabelEntry constructor can add a new binding to the parentWidget.entry widget 
to perform the validation. 

The validation is performed in a method of the val idatedLabelEntry class. The bind command 
in the constructor uses the self command to register the method as a script to invoke and adds the 
name of the entry widget to the script. 

When a key is released, the validatedLabel Entry class’s validate method is invoked. If the 
string in the entry widget is valid, it is configured for black letters on a white background. If it’s not 
valid, the entry widget is configured for inverse video. 


$A AAAA_|q_ 


Example 27 
Script Example 
proc ::00::define::classmethod {name {args ""} {body ""}} { 


if Create the method on the class if the caller gave 
## arguments and body 
if {Cllength [info level 0]] == 4} { 

uplevel 1 [list self method $name $args $body] 
} 
## Get the name of the class being defined 
set cls [lindex [info level -1] 1] 
i## Make connection to private class 
if forwarding 


y" command by 
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uplevel forward $name Linfo object namespace $cls]::my $name 


00::class create labelEntry { 
variable State 
superclass oo::class 


classmethod unknown {w args} { 
if {Lstring match .* $w]} { 
[self] new $w {x}$args 
return $w 
} 
next $w {x}$args 
} 


constructor {widgetName args} { 


set State(parent) [frame $widgetName -class labelEntry] 


re 
re 


Q 


e ::$widgetName ::$widgetName. frame 
e [self] ::$widgetName 


Q 


## A label named label and an entry widget named entry. 
label $State(parent).label 
entry $State(parent).entry 


it Grid the widgets in the frame 
grid $State(parent).label $State(parent).entry 


my configure {x}$args 


method configure {args} { 
if Step through the args and apply them as required. 
# "“-entry.width" becomes "parent.entry configure -width" 


foreach {k v} $args { 
lassign [split $k .] type opt 
set type [string trim $type -] 
if {Lcatch {$State(parent).$type configure -$opt $v} err]} { 
puts "FAILED: $State(parent).$type configure -$opt $v" 
puts $err 
} 
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00::cla 


varia 
super 


ss create validatedLabelEntry { 


ble State 
class labelEntry 


classmethod unknown {w args} { 


if 
[: 
r 


} 
nex 
} 


const 
if 
e 
j 
} 
set 


nex 
bin 


metho 


vi 


sé 


# 
# 


} 


if An ex 
if one n 


validat 
validat 


{Lstring match .* $w]} { 
self] new $w {*}$args 
eturn $w 


t $w {*x}$args 


ructor twinName args} { 

{Lcatch {dict get $args -validate} State(dataType)]} { 
rror "validatedLabelEntry must include -validate\n\ 
nteger, alpha, graph, etc" 


args [dict remove $args -validate] 
t $winName {x}$args 
d $winName.entry <KeyRelease> \ 
"[self] validate $winName.entry" 


d validate {entryWidget} { 
Get the current contents of the entry widget 
t tmp [$entryWidget get] 


f the string is valid, entry widget is black on white 
f the string is not valid, entry uses reverse video 
{Lstring is $State(dataType) $tmp]} { 

y configure -entry.background white 

y configure -entry.foreground black 

else { 

y configure -entry.background black 

y configure -entry.foreground white 


ample of use with one alphabetic entry and 
umeric entry. 


edLabelEntry .name -label.text Name -validate alpha 
edLabelEntry .age -label.text Age -validate integer 
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grid .name 
grid .age 


Script Output 
The name Ralph 124C41+ contains non-alphabetic characters, so it is in reverse video. The string 
0x64 is a valid integer, so it is in normal video. 


e This chapter has described the megawidgets included in the Tk distribution and shown how megaw- 
idgets can be constructed using Tk without any C language extensions using either namespaces or 
TclOO. 

e The megawidgets included in the Tk distribution are: 

Syntax: tk_optionMenu buttonName varName vall ?val2...valIN? 
Syntax: tk_chooseColor 
Syntax: tk_getOpenFile ?option value? 
Syntax: tk_getSaveFile ?option value? 
Syntax: tk messageBox ?option value? 
Syntax: tk_dialog win title text bitmap default \ 
stringl ?... stringN? 
Syntax: tk_popup menu x y ?entry? 

e You can determine what windows (if any) have grabbed events with the grab current command. 
Syntax: grab current ?window? 

e You can determine whether a window that is grabbing events is grabbing them for the local task or 
all tasks with the grab status command. 

Syntax: grab status window 

e A Tk window can be declared to be the recipient of all keyboard and mouse events with the grab 
command. 
Syntax: grab set ?-global? window 

e The rename command will change the name of a command. 

Syntax: rename oldName ?newName? 

e You can define a default value for various options with the option add command. 
Syntax: option add pattern value ?priority? 

e The namespace current command will return the full name of the current namespace. 
Syntax: namespace current 

e The namespace code command will wrap a script so that it can be evaluated in the current space. 
Syntax: namespace code script 

e A Tk script can be forced to wait for an event to occur with the tkwait command. 
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Syntax: tkwait EventType name 

e A megawidget can be made modal with the grab, focus, and tkwait commands. 

e You can construct your own megawidgets by providing a wrapper procedure that arranges widgets 
within a frame. 

e The name of a frame can be disassociated from the name of the procedure used to configure the 
frame with the rename command. 

e Megawidgets can be built using namespaces to conceal the internal structure of the megawidget. 

e Megawidgets can be built using TclOO to conceal the internal structure of the megawidget. It is 
easier to retain state information with a TclOO class than a namespace because each widget gets a 
private state with a class but shares state with all widgets that use a namespace. 

e Megawidgets can be nested within other megawidgets to support more complex interactions. This 
can be done with both namespace-based and TclOO-based megawidgets. 

e TclOO-based megawidgets can inherit and extend functionality from other TclOO-based mega- 
widgets. 

e A TclOO-based megawidget needs to use the se] f command to register a method as a callback for 
a primitive widget, bind, trace or other command that registers a callback. 

e A TclOO class uses the my varname to link an object variable to a widget (as with the 
-textvariable option). 

e The next command transfers control to a superclass or mixin method with the same name as the 
current method. The next command can be used at any position in a method. 


14.12 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range __ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under 
a minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page, or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material, or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e 100 Which standard megawidget will allow a user to select an existing file from which to load 
data? 


e 101 Which standard megawidget will allow a user to select a new file to which data can be written? 


e 102 Which standard megawidget provides a generic dialog facility? 
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103 Can an application be written to use a Motif-style file selector on a Windows platform, instead 
of the native Windows-style file selector? 


104 Which standard megawidget will give a user the option of selecting “Yes” or “No” as the 
answer to a question? 


105 What two commands will follow this code fragment to: 
a. Configure the frame with a red background? 
b. Grid the frame in row 1, column 2? 

frame .f 

rename .f myFrame 


106 What command would set the font for all buttons to {Times 24 bold}? 
107 What command will force a wish script to pause until the window .1 is destroyed? 


108 If the button .b is clicked after the following code fragment has executed, will the application 
exit? If not, why? 

pack [entry .e -textvar tst] 

pack [button .b -text "EXIT" -command "exit"] 

update 

grab set .e 


109 What option to grab will cause all events to be trapped by an application? 

110 What command will transfer control to a superclass method? 

111 What command will define an object variable as a label’s -textvariable? 
112 Can two megawidget objects of the same class be used in a compound widget? 


200 Write a procedure that will accept a frame name as an argument, and will create a frame with 
that name and grid a text widget and scrollbar into the frame. The procedure should return the 
name of the text widget. 


201 Using the TclOO pattern described in Section 14.10.1, construct a megawidget with a label, 
and a canvas below it. 


202 Modify the megawidget constructed in the previous exercise to accept the following options. 
-jmage imageName 
An image to display in the canvas. 
-title text 
Text to display in the l1abel widget. 


203 Write a procedure that will create a new top-level window and wait for a user to click one of 
two buttons. The return from the procedure will be the text of the button that was clicked. 


204 Modal widgets are commonly created in a new top-level window. Can a modal widget be 
created within a frame? Why or why not? 


300 Use the pattern described in Section 14.10.2 to create a megawidget with a prompt, an entry 
widget, and a listbox. Allow a user to type a value into the entry widget, or select a value from 
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the listbox. When a listbox entry is selected, it should appear in the entry box. The widget should 
support the following widget procedures. 

insert value 

Insert a value into the listbox. 

get 

Get the content of the entry widget. 


e 301 Expand the label Entry example from Section 14.10.2 to include a cget method which will 
return the value of a configuration option for an internal widget. Use the 
-widgetName.optionName naming convention that was used for the configure 
command—.e., the foreground attribute of the entry widget is identified as 
-entry. foreground. 


e 302 Modify the scrolledLB widget from Section 14.5.4 from a namespace-based compound 
widget to be a TclOO class. 


e¢ 303 Modify the filteredLB megawidget from Section 14.7 to work as a TclOO-based widget. 
Use the TclOO-based scrol]edLB widget reworked in Exercise 302. 


e 304 The filteredLB compound widget can be created as an aggregate of two scrolledLB 
objects and a button. Use the fi 1 teredLB class from Exercise 303 as a superclass and create a 
file selector similar to the one described in Section 14.8.3. 


CHAPTER 


Extending Icl 


One of the greatest strengths of the Tcl package is the ease with which it can be extended. By adding 
your own extensions to the interpreter you can: 


e Use compiled code to perform algorithms that are too computation-intensive for an interpreted 
language. 

e Add support for devices or data formats that are not currently supported by Tcl. 

e Create a rapid prototyping interpreter for an existing C language library. 

e Add Tk graphics to an existing application or set of libraries. 

e Create a script-driven test suite for an application or library. 


Extensions can be linked with the Tcl library to create a new tclsh or wish interpreter, or they can 
be loaded into a running tclsh . Note that support for loading binary objects into a running tcl sh 
requires a version of the Tcl library that is more recent than 7.5 and an operating system that supports 
dynamic runtime libraries. Microsoft Windows, Macintosh OS, Linux, and many flavors of UNIX 
support this capability. 

Whether you are building a new tcl sh ora loadable binary package, and whether you are linking 
to an existing library or are writing your own functions, the steps to follow are the same. This chapter 
describes the components of an extension, steps through creating a simple Tcl extension, discusses how 
to move data between the Tcl interpreter and your C language functions, and discusses how to handle 
complex data such as structures. 

In Tcl version 8.0 a major modification was introduced to the Tcl internals. Prior to this (Tcl 7.x and 
earlier), all data was stored internally as a string. When a script needed to perform a math operation, the 
data was converted from string to native format (integer, long, float, double, and so on), the operation 
was performed, and then the native format data was converted back to a string to be returned to the 
script. This process caused Tcl scripts to run rather slowly. 

With Tcl revision 8.0 and later, the data is stored internally in a Tc1_0bj structure. The Tc1_0bj 
structure contains a string representation of the data and a native representation of the data. The two 
representations are kept in sync in a lazy manner; the native and string representations are calculated 
when needed and retained as long as they are valid. 

This change improved the speed of the Tcl interpreter, while adding minimal complexity for exten- 
sion writers. Most of the Tcl library functions that interface with data now come in two forms: one to 
deal with old-style string data and one to deal with new-style Tc1_Obj data. 

If you are writing a new extension, you can use all of the new Tc1_Obj -oriented commands (which 
have the word Obj in their names). If you need to link with an earlier version of Tcl (for instance, if 
you need to use an extension that exists only for Tcl 7.5), you will need to use the older version of the 
commands. 
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This chapter covers both sets of commands. If you do not need to be able to link with an older 
version of Tcl, it is recommended that you use the Tc1_0bj objects for your data and the Tc1_0bj API 
to interface with the interpreter. 

This chapter provides an overview of how to construct an extension, first from the functional view- 
point of what functionality is required in an extension and how the parts work together and then from 
the structural viewpoint of how the code modules should be assembled. This is followed by an exam- 
ple of a simple extension, and discussions of more advanced topics, such as using lists and arrays, and 
creating extensions with subcommands. 


15.1 FUNCTIONAL VIEW OF A TCL EXTENSION 


The interface between the Tcl library and an extension is implemented with several functions. On 
Windows systems these are documented under the Tcl Library Procedures entry in the Tcl Help menu. 
On UNIX systems, they are documented in files named Tc/_*.3 in the doc directory. On the Macintosh 
these functions are documented under the HTML DOCS folder. The required commands are described 
in this chapter, but read the on-line documentation for more details. 

The interface to the Tcl library includes several data types that are specific to Tcl. Those we will be 
dealing with are as follows. 
Tcl_Interp * A pointer to a Tcl interpreter state structure. 


Tcl_ObjCmdProc * A pointer to a function that will accept Tcl objects as arguments. 


Tcl_CmdProc * A pointer to a function that will accept strings as arguments. 
ClientData A one-word value that is passed to functions but never used by the Tcl 
interpreter. This allows functions to use data that is specific to the appli- 
cation, not the interpreter. For instance, this argument could be used to 
pass a pointer to a database record, a window object, or a C++ this 
pointer. 


15.1.1 Overview 
An extension must implement the following sets of functionality. 


e Initialize any persistent data structures. 

e Register new commands with the Tcl interpreter. 
e Accept data from the Tcl interpreter. 

e Process the new commands. 

e Return results to the calling scripts. 

e Return status to the calling scripts. 


15.1.2 Initialize Any Persistent Data Structures 

Your extension must include an initialization function that will be called by the Tcl interpreter when 
the extension is loaded into the interpreter. The code that performs the initialization will depend on 
your application. 
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15.1.3 Register New Commands with the Interpreter 


You register a new command with the Tcl interpreter by calling a function that will insert the name 
of the new command into the Tcl command hash table and associate that name with a pointer to a 
function that will implement the command. There are two functions that can be invoked to register a 
new command with the Tcl interpreter. One will register the new command as a function that can use 
Tcl objects, and the other will register the new command as a function that requires string arguments. 
Extensions that are to be linked with versions of Tcl more recent than 8.0 should create Tcl object-based 
functions rather than string-based functions. 


Syntax: int Tcl_CreateObjCommand (interp, cmdName, func, clientData, 
deleteFunc) 


Syntax: int Tcl_CreateCommand (interp, cmdName, func, clientData, 
deleteFunc) 


Tcl_CreateObjCommand Tcl_CreateCommand 


These functions register a new command with the Tcl interpreter. The following 
actions are performed within the Tcl interpreter. 


e Register cmdName with the Tcl interpreter. 

e Define clientData data for the command. 

e Define the function to call when the command is evaluated. 
e Define the command to call when the command is destroyed. 


Tcl_CreateCommand is the pre-8.0 version of this command. It will still work with 
8.0 and newer interpreters but will create an extension that does not run as fast as 
an extension that uses Tc1_CreateObjCommand. 

Tcl_Interp *xinterp 


This is a pointer to the Tcl interpreter. It is required by all commands that need to 
interact with the interpreter state. Your extensions will probably just pass this 
pointer to Tcl library functions that require a Tcl interpreter pointer. Your code 
should not attempt to manipulate any components of the interpreter structure 
directly. 

char *xcmdName 
The name of the new command, as a NULL-terminated string. 


Tcel_CmdProc x*func 


Tcl_ObjCmdProc xfunc 


The function to call when cmdName is encountered in a script. A pointer to a 
Tcl_CmdProc * is used with pre-8.0 interpreters, and a pointer to a 
Tcl_0bjCmdProc is used with recent interpreters. 
ClientData clientData 
A value that will be passed to func when the interpreter encounters cmdName and 
calls func. The ClientData type is a word, which on most machines is the size of 
a pointer. You can allocate memory and use this pointer to pass an arbitrarily large 
data structure to a function. 
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Tcl_CmdDeleteProc *xdeleteFunc 


A pointer to a function to call when the command is deleted. If the command has 
some persistent data object associated with it, this function should free that memory. 
If you have no special processing, set this pointer to NULL, and the Tcl interpreter 
will not register a command deletion procedure. 


These commands will return TCL_OK to indicate success or TCL_ERROR to indicate a failure. These 
are defined in the file tc]. h, which should be ##i nc] uded in your source. 


Tcl_CreateObjCommand(interp, "demo", Demo_Cmd, 
(ClientData) NULL, NULL); 


Modern Tcl extensions create the new commands in a namespace. To create new commands within 
a namespace, simply add the namespace identifier to the name of the command being added to the 
interpreter, as in the following example. 


Tcl_CreateObjCommand(interp, "demoNamespace::demo", Demo_Cmd, 
(ClientData) NULL, NULL); 


15.1.4 Accept Data from Tcl Interpreter 

When a command is evaluated, the interpreter needs to pass data from the script to the function. The Tcl 
interpreter handles this with a technique similar to that used by the C language for receiving command 
line parameters. The function that implements the C command receives an integer argument count and 
an array of pointers to the Tcl script arguments. For example, if you register a command f 00 with the 
interpreter as 


Tcl_CreateObjCommand(interp, "foo", fooCmd, NULL, NULL); 
and later write a script command 
foo one 1 two 2 


fooCmd will be passed an argument count of 4 and an argument list that contains one, 1, two,and 2. 
When the Tcl interpreter evaluates the Tcl command associated with a function in your extension, it 
will invoke that function with a defined set of arguments. If you are using Tcl 8.0 or newer and register 
your command using Tcl_CreateObjCommand, the Tcl command arguments will be passed to your 
function as an array of objects. If you are using an older version of Tcl or register your command using 
the Tcl_CreateCommand function, the arguments will be passed as an array of strings. The function 
prototype for the C function that implements the Tcl command will take one of these two forms: 


Syntax: int func(clientData, interp, objc, objv) 
Syntax: int func(clientData, interp, argc, argv) 
func The function to be called when cmdName 1s evaluated. 


ClientData clientData This value was defined when the command was 
registered with the interpreter. 

Tcl_Interp xinterp A pointer to the Tcl interpreter. It will be passed to Tcl 
library commands that need to interact with the 
interpreter state. 


int objc The count of objects being passed as arguments. 
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Tcl_0bj *objv[ ] An array of Tcl objects that were the arguments to the Tcl 
command in the script. 


int argc In pre-8.0 versions of Tcl, this is the count of argument strings 
being passed to this function. 


char xargv[ ] In pre-8.0 versions of Tcl, this is an array of strings. Each array 
element is an argument passed to the Tcl command. Versions of 
Tcl prior to 8.0 used strings instead of objects for arguments. 
The objects are much more efficient and should be used unless 
you have compelling reasons for maintaining compatibility with 
older code. 


If you are using Tcl version 8.0 or newer and register the command with the 
Tcl_CreateObjCommand function, your function must accept an array of Tc1_0bj pointers. If you 
are using a version of Tcl older than 8.0, your function must accept arguments as an array of char 
pointers. In either case, the third argument will be an integer that describes the number of argu- 
ments in the array. Your function may return TCL_OK, TCL-ERROR, TCL_-RETURN, TCL_BREAK, or 
TCL_CONTINUE . The most frequently used codes are TCL_OK and TCL_ERROR. 

TCL_BREAK, TCL_RETURN, and TCL_CONTINUE are used for building program flow control com- 
mands such as looping or branching commands. Since Tcl already includes a complete set of looping 
and branching commands, if you think you need to implement a new flow control command you may 
want to look at your application very closely to see if you have missed an existing command you 
could use. 


Converting Tcl Data to C Data 
Once your function has been called, you will need to convert the data to the format your function (or 
the library calls it invokes) can use. In versions of Tcl earlier than 8.0, all data was stored as strings. 
Whenever data was needed in another format, it needed to be converted at that point, and the native 
format of the data was discarded when that use was finished. 

With Tcl 8.0 and newer, the data is stored internally in a structure that maintains both a string and 
a native representation of the data. In this case, your function can use Tcl’s support for extracting the 
values from the Tc1_0bj structure. 


Data Representation 

In order to convert the data, you need to know a little about how the Tcl interpreter stores data internally. 
With versions of Tcl that pass the arguments as strings, you can convert the data from the Tcl script to 
native (int, float, and so on) format with the standard library calls sscanf, atof, atol, strtod, 
strtol, strtoul, and so on. 

As of Tcl 8.0, the Tcl interpreter stores data in Tc1_0bj structures. The Tc1_Obj structure stores its 
data in two forms: a string representation and a native representation. The data in a Tc1_Obj object is 
accessed via a set of function calls that will be discussed later in this section. 

It is not necessary to know the details of the Tc1_Obj structure implementation, because all interac- 
tions with a Tcl object will be done via Tcl library functions, but you will understand the function calls 
better if you understand the design of the Tc1_Obj structure. The two primary design features of the 
Tcl object are the data’s dual-ported nature (the string and native representations) and the interpreter’s 
use of references to objects rather than copies of objects. 
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A Tcl_0bj structure maintains a string representation of the data as well as the native represen- 
tation. The conversion between these two representations of the data (the dual nature of the object) 
is handled in a lazy manner. The data is converted between formats only when necessary. When one 
representation of the data is modified, the other representation is deleted to indicate that it must be 
regenerated when needed again. For example, in the commands: 


set x "12" 
The Tcl interpreter creates an object and defines the string representation as 12. 
puts "The value of X is: $x" 


The puts command does not require a conversion to native mode, so the string 
representation of $x is displayed and no conversion to integer is made. 


incr x 2 


The string representation of the data in the $x object is now converted to native 
(integer) representation, and the value 2 is added to it. The old string representation 
is cleared to show that the native representation is valid. 


set y Lexpr $xt2] 


When $x is accessed by the expr command, the object’s native representation is 
used. After the addition is performed, a new object is created to hold the result. 
There is no need to convert the integer representation of x into a string, so it 
will be left blank. This new object is assigned to the variable y, with a native 
representation (integer) but no string representation defined. 

puts "The value of Y is: $y" 


When the puts is evaluated, the Tcl script needs a string representation of the object, 
the integer is then converted to a string, and the string representation is saved for 
future use. 

If the value of $x were only displayed and never used for a calculation (as a report generator would 
treat the value), it would never be converted to integer format. Similarly, if the value of $y were never 
displayed (simply used in other calculations), the conversion to a string would never be made. Since 
most applications deal with data in native or string representation in batches, this lazy conversion 
increases the speed of the Tcl interpreter. 

Converting data from one format to another is referred to as shimmering. These conversions can 
slow a program. Avoiding such behavior will improve program speed slightly, but are usually not the 
limiting factor in program speed. 

The reference counts associated with Tcl objects allow the Tcl interpreter to maintain pointers to 
objects, instead of making copies of any objects referenced in more than one location. This lets the 
interpreter maintain a smaller number of objects than would otherwise be necessary. When an object is 
created, it is assigned a reference count of 0. 

When a Tcl object is referenced by other objects (for example, the object is associated with a vari- 
able), the reference counter is incremented. The reference counter will be incremented by one when a 
variable is declared as the - textvariable fora ]abel or passed as an argument to a procedure. When 
an object that references another Tcl object is destroyed (with the unset command or by destroying an 
associated widget), the reference count for the associated object is decremented by one. If the reference 
count becomes 0 or less, the object is deleted and its memory is returned to the heap. 
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Obtaining the Data 

Since arguments are passed to your function in an array of pointers, the function can access data as 
argumentLO], argument[1], and so on. For example, if you register your command using the 
Tcl_CreateCommand function, you could print out the arguments to a function with code such as the 
following. 


int myFunc(ClientData data, Tcl_Interp xinterp, 
int argc, char *xargv) { 


int i; 
for (i=0; i<argc; i++) { 
printf("argument %d is %s\n", i, argvLli]); 


} 
} 


Recent versions of Tcl pass the data as an array of pointers to Tcl objects. In that case you need to 
use the Tcl conversion functions to extract either the string or native representation of the data. 


Syntax: int Tcl_GetIntFrom0bj(interp, objPtr, intPtr) 


Tcl_GetIntFrom0bj Retrieve an integer from the object. 

Tcl_Interp *interp A pointer to the Tcl interpreter. 

Tcl_Obj *objPtr A pointer to the object that contains an integer. 
int *intPtr A pointer to the integer that will receive this data. 


Syntax: int Tcl_GetDoubleFrom0bj(interp, objPtr, dbiPtr) 
Tcl_GetDoubleFrom0bj Retrieve a double from the object. 


Tcl_Interp *interp A pointer to the Tcl interpreter. 
Tcl_Obj *objPtr A pointer to the object that contains a double. 
Double xdb/iPtr A pointer to the double that will receive this data. 


The Tcl_GetIntFrom0bj and Tcl_GetDoubleFromO0bj functions return a TCL_OK if they suc- 
cessfully extract a numeric value from the object, or return TCL_ERROR if they cannot generate a 
numeric value for this object. (For instance, if the object contains an alphabetic string, there is no 


integer or floating-point equivalent.) 
Tcl data is always available as a string. When you need to get the string representation of an object’s 
data, you use the Tc]l_GetStringFrom0bj command. 


Syntax: char *Tcl_GetStringFrom0bj (objPtr, lengthPtr) 
Tcl_GetStringFrom0bj Retrieve a byte string from the object. 
Tcl_Obj *objPtr A pointer to the object that contains a string. 
int xlengthPtr A pointer to an int that will receive the number of 
characters in this data. If this value is NULL, the 
length will not be returned. 


Note that the Tcl_GetStringFromObj function does not follow the format of the previous Get 
functions. It returns the requested data as a char pointer rather than returning a status. Since the data 
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is always available in a string format, this command can fail only if the object pointer is invalid, in 
which case the program has other problems and will probably crash. 

The Tcl_GetStringFrom0bj command can place the number of valid bytes in the char pointer in 
an integer pointer (1 engthPtr). The data in a string may be binary data (accessed via the Tcl binary 
command, for instance), in which case the length pointer is necessary to track the number of bytes in 
the string. 


15.1.5 Returning Results 
The function implementing a Tcl command can return results to a script in the following ways. 


e Return a single value as the result. 

e Return a list of values as the result. 

e Modify the content of a script variable named as an argument. 
e Modify the content of a known script variable. 


If you desire to have your function return a value to the script as the result of evaluating the com- 
mand (which is how most functions return their results), your code must call a function that sets the 
return to be a particular value. In old versions of Tcl, this can be done by passing a string. The modern 
Tcl interpreters require your code to create a new Tcl_Obj. The object created within the function 
will have a reference count of 0. If the return value from the function is assigned to a variable, the 
object’s reference count will be incremented; otherwise, the object will be deleted when the command 
has finished being evaluated. You can create a new object with one of the following commands. 


+ 


Syntax: Tcl_0bj 


J 


Tcl_NewIntObj (intValue) 
Syntax: Tcl_Obj *Tcl_NewDoubleObj (dbiValue) 


J 


Syntax: Tcl_O0bj *Tcl_NewStringObj (bytes, length) 
Tcl_NewIntObj Create a new Tcl object with an integer value. 
Tcl_NewDoubleQbj Create a new Tcl object with a double value. 


Tcl_NewStringObj Create a new Tcl object from a byte string. 


intValue The integer to assign to the new object. 

db] Value The double to assign to the new object. 

bytes An array of bytes to copy to the new object. 

length The number of bytes to copy to new object. If this is a 
negative value, all bytes up to the first NULL byte will be 
copied. 


In Tcl earlier than 8.0, since all variables were maintained as strings, a function could create an 
ASCII string to return with the sprintf command or could modify data in an existing string with the 
standard string library commands. After a return value has been created, it can be assigned with one of 
the following commands. 


Syntax: void Tcl_SetObjResult (interp, objPtr) 
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Syntax: void Tcl_SetResult(interp, string, freeProc) 

Tcl_SetObjResult Makes the Tcl interpreter point to obj Ptr as the result 
of this function. If this function has already had a result 
object defined, that object will be replaced by the object 
pointed to by objPtr. This function should be used with 
Tcl 8.0 and more recent versions. 


Tcl_SetResult Copies the string into the result string for this function, 
replacing any previous string that was there. This 
function is for use with pre-8.0 versions of Tcl. 


Tcl_Interp *interp A pointer to the Tcl interpreter. 


Tcl_Obj *objPtr A pointer to the object that will become the result. 
char *string A string to copy to the object. 
freeProc The name of a procedure to call to free the memory 


associated with the string when this object is destroyed. 
Must be one of: 


TCL_STATIC 


The string was defined in static memory and will remain 
constant. 


TCL_DYNAMIC 


The memory for the string was allocated with a call to 
Tcl_Alloc. It will be returned to the Tcl memory pool. 


TCL-VOLATILE 


The string was allocated from a nonpersistent area of 
memory (probably declared on the call stack) and may 
change when the function exits. In this case, the Tcl 
interpreter will allocate a safe space for the string and 
copy the memory content. 


If the new command needs to return several pieces of information, you may prefer to pass the 
command the name of one or more Tcl variables to place the results in. This is similar to passing 
pointers to a C function. In this case, the code will modify the content of an existing Tcl variable. 

The most generic function for modifying a Tcl variable is Tc]_SetVar. This function will accept 
the name of a variable and will either modify an existing variable or create a new variable by that name. 
The value to be assigned is passed to this function as a string, which can be easily obtained from a Tcl 
object, or generated as needed. 


Syntax: char *«Tcl_SetVar(interp, varName, newValue, flags) 
Tcl_SetVar Assign a value to a variable. Create a new Tcl 
variable if necessary. 


interp The pointer to the Tcl interpreter. 


varName A NULL-terminated string containing the name of 
the variable. 
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newValue 


flags 


A NULL-terminated string containing the value to be 


assigned to this variable. 


One or more or’d-together flags to fine tune the 


behavior of the assignment. By default (0), the value 
is assigned as a string to a variable in the current 
scope when the command is invoked. The flags may 
be one or more of: 


TCL_GLOBAL_ONLY 


TCL_NAMESPACE_ONLY 


TCL_LEAVE_ERR_MSG 


TCL_APPEND_VALUE 


TCL_LIST_ELEMENT 


When Tcl tries to resolve the name to a Tcl 
variable, it will look in the global scope, instead 
of the local scope. 


Tcl looks for a variable defined only within the 
current namespace. 


If this is set and an error occurs, the error message 
is left in the interpreter’s result string. The error 
message can be retrieved with the 
Tcl_GetObjResult or Tcl_GetStringResult 
function. 

Setting this bit causes the new value to be 
appended to the original data in the variable. 

If this flag is set, the new value is converted to a 
valid Tcl list element before being assigned (or 
appended) to the variable. 


If your code has access to a Tcl object, it can assign a native format value to the variable with one 
of the following commands. 


Syntax: void Tcl_SetIntObj (objPtr, 


Syntax: void Tcl_SetDouble0bj 


jo) 


1 
(2) 


1 
2) 


= 


do 


intValue) 


(objPtr, dblValue) 

1_SetIntObj Set the value of the integer representation of an 
object. If the object was not already an integer type, it 
will be converted to one if possible. 


1-SetDouble0bj Set the value of the integer representation of an 
object. If the object was not already a double type, it 
will be converted to one if possible. 
1_0bj *objPtr A pointer to the object that will contain the new value. 
t intValue The integer to assign to this object. 
ble dblValue The double to assign to this object. 


An object’s string representation can be modified in several ways, either completely replacing one 
byte string with a new byte string, appending a single string, appending a string from another object, 
or appending a list of strings. 
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Syntax: void Tcl_SetStringObj (objPtr, bytes, length) 

Syntax: void Tcl_AppendToObj (objPtr, bytes, length) 

Syntax: void Tcl_AppendObjToObj (objPtr, appendObjPtr) 

Syntax: void Tcl_AppendStringsToObj (objPtr, string, ...,NULL) 


cl_SetStringObj 
Tcl_AppendToObj 


Tcl_AppendObjTo0bj 


Tcl_AppendStringsTo0bj 


Tcl_Obj xobjPtr 
char *bytes 


Redefine the string value of an object. 


Append a string to the string representation of 
the data in an object. 


Append the string representation of the value of 
one object to the string currently in an object. 


Append one or more strings to the string 
currently in an object. 


A pointer to the object that contains the string. 


An array of bytes to copy to the object. 


—————— 
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char xstring 


be appended. 


intlength The number of bytes to copy to the new object. 
If this is a negative value, all the bytes up to the 
first NULL byte will be copied. 

Tcl_Obj *appendObjPtr A pointer to an object that contains a string to 


A NULL -terminated string of characters. You 


may not use a binary string with the 
Tcl_AppendStringsToObj command. 


15.1.6 Returning Status to the Script 


When a function returns execution control to the Tcl interpreter, it must return its status. The sta- 
tus should be either TCL_OK or TCL_ERROR. If the function returns TCL_OK, the object defined by 
Tcl_SetObjResult will be returned to the script, and script will continue execution. If the func- 
tion returns TCL_ERROR, an error will be generated, and unless your script is trapping errors with the 
catch command the execution will stop and error messages will be returned. 

By default, the error messages returned will be the Tcl call stack leading to the Tcl command that 
caused the error. You may want to add other information to this, such as why a file write failed, what 
database seek did not return a value, or what socket can no longer be contacted. You can add more 
information to that message by invoking the function Tcl_AddErrorInfo, Tcl_SetErrorCode, 
Tcl_AddObjErrorInfo, or Tcl_SetObjErrorCode. 


Syntax: 
Syntax: 
Syntax: 
Syntax: 


void 
void 
void 


void 


Tcl_AddObjErrorInfo 


Tcl_AddErrorInfo (interp, message) 


Tcl_AddObjErrorInfo (interp, message, 


Tcl_SetObjErrorCode (interp, objPtr) 


Tcl_SetErrorCode (interp, elementl, element2 


length) 


. NULL) 


Append additional text to the information object. This 


information object can be accessed within the Tcl 
script as the global variable errorInfo. 
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Tcl_-AddErrorInfo Append additional text to the information to be 
returned to the script. This function should be used 
with versions of Tcl before 8.0. 


Tcl_SetObjErrorCode Set the errorCode global variable to the value 
contained in the Tcl object. If the object contains a 
list, the list values are concatenated to form the 
return. By default errorCode will be NONE. 


Tcl_SetErrorCode Set the errorCode global variable to the value of the 
concatenated strings. 

Tcl_Interp *interp A pointer to the Tcl interpreter. 

char *message The message to append to the errorInfo global 


variable. This string will have a new] ine character 
appended to it. 


Tcl_Obj *objPtr A pointer to the object that will contain the error code. 


char *xelement A NULL-terminated ASCII string representation of a 
portion of the error code. 


If a system error occurs, your function can invoke Tcl_PosixError to set the errorCode vari- 
able from the C language global errno. The behavior of this command varies slightly for different 
platforms. You should check the on-line documentation for your platform and Tcl revision before 
using it. 


15.1.7 Dealing with Persistent Data 

There are circumstances in which an extension needs to maintain a copy of some persistent data sepa- 
rate from the script that is being evaluated, while allowing the script to describe the piece of data with 
which it needs to interact. For instance, a file pointer must be maintained until the file is closed, and a 
Tcl script may have several files open simultaneously, accessing one file and then another. 

If your extension’s data requirements are simple, it may be sufficient to allocate an array of items 
and assign them to scripts as necessary. For instance, if you write an extension that interfaces with a 
particular piece of hardware and there will never be more than one of these devices on a system, you 
may declare the control structure as a static global in your C code. 

For more complex situations, the Tcl library includes functions that let you use a Tcl hash table 
to store key and value pairs. Your extension can allocate memory for a data structure, define a key to 
identify that structure, and then place a pointer to the structure in the hash table, to be accessed with 
the key. The key may be an alphanumeric string that can be returned to the Tcl script. When a Tcl script 
needs to access the data, it passes the key back to the extension code, which then retrieves the data 
from the hash table. 

The Tcl hash table consists of a Tc]_HashTab1e structure that is allocated by your extension code 
and Tcl_-HashEntry structures that are created as necessary to hold key/value pairs. You must initial- 
ize the hash table before using it with the functions that access hash table entries. Once the table is 
initialized, your code can add, access, or delete items from the hash table. 
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Syntax: void Tcl_InitHashTable (tablePtr, keyType) 

Tcl_InitHashTable Initializes the hash table. 

Tcl_HashTable xtablePtr A pointer to the Tcl_HashTable structure. The 
space for this structure must be allocated before 
calling Tcl_InitHashTable. 


int keyType A Tcl hash table can use one of three different 
types of keys to access the data saved in the hash 
table. The acceptable values for keyType are: 


TCL_STRING_KEYS The hash table will use a NULL-terminated 
string as the key. This is the most commonly 
used type of hash key. The string representation 
of a Tcl_0bj object can be used as the key, 
which makes it simple to pass a value from a 
script to the Tcl hash table functions. 

TCL_ONE_WORD_KEYS The hash table will use a single-word value as 
the key. Note that if the word is a pointer, the 
value of the pointer is used as the key, not the 
data that the pointer references. 


positivelInteger If a positive integer is used as the keyType, the 
key will be an array of the number of integers 
described. This allows complex binary data 
constructs to be used as keys. Note that the 
constructs used as keys must be the same size. 


Once a hash table has been initialized, the Tcl_CreateHashEntry, Tcl_FindHash Entry, and 
Tcl_DeleteHashEntry commands can be used to create, query, or remove entries from the hash table. 


Syntax: Tcl_HashEntry x*Tcl_CreateHashEntry(tablePtr, key, newPtr) 
Syntax: Tcl_HashEntry x*Tcl_FindHashEntry(tablePtr, key) 


Syntax: void Tcl_DeleteHashEntry(entryPtr) 

Tcl_CreateHashEntry Allocates and initializes anew Tcl_HashEntry object 
for the requested key. If there was a previous entry 
with this key, newPtr is set to NULL. 
Tcl_FindHashEntry This function returns a pointer to the Tcl_HashEntry 

object that is associated with the key value. If that key 
does not exist in this hash table, this function returns 
NULL. 

Tcl_DeleteHashEntry This removes a hash table entry from the table. After 
this function has been called, Tc]_FindHashEntry 
will return a NULL if used with this key. This does not 
destroy data associated with the hash entry. Your 
functions that interact with the hash table must do that. 
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Tcl_HashTable *tablePtr 


char *key 


int *xnewPtr 


Tcl_HashEntry xentryPtr 


A pointer to a Tcl hash table. This table must be 
initialized by Tcl_InitHashTable before being 
used by these commands. 

The key that defines this entry. This value must be 
one of the types described in the 
Tcl_InitHashTable call. 

This value will be 1 if a new entry was created, and 
0 if a key with this value already existed. 


A pointer to a hash table entry. 


A Tcl_HashEntry contains the key value that identifies it and a ClientData data object. The 
ClientData type is a word-sized object. On most modern machines, this is the same size as a 
pointer, which allows you to allocate an arbitrary data space and place the pointer to that space in a 
Tcl_-HashEntry. You can manipulate a Tcl_HashEntry object with the Tcl_SetHashValue and 


Tcl_GetHashValue commands. 


Syntax: ClientData TclGetHashValue (entryPtr) 


Syntax: void TclSetHashValue (entryPtr, value) 


TclGetHashValue 
TclSetHashValue 


cl_HashEntry xentryPtr 


ClientData value 


Retrieve the data from a Tc]_HashEntry. 
Set the value of the data ina Tcl_HashEntry. 
A pointer to a hash table entry. 


The value to be placed in the cli entData field 
of the Tcl_HashEntry. 


The following code will create a hash table, add an entry, and retrieve the data. 


2m 


Example 1 
Code Example 
void hashSnippet () { 


// The hash table pointer 
Tcl_HashTable xhashTable; 
Tcl_HashEntry *firstEntry; 


// the table 
Tcl_HashEntry *secondEntry; 


int isNew; 
char *insertData, xretrievedData; 
char *key; 


key = "myKey"; 


// firstEntry will point to a hash entry we create 


// secondEntry will point to a hash entry extracted from 


insertData = "This is data in the hash table"; 


} 


15.1 Functional View of a Tcl Extension 


// Allocate the space and initialize the hash table 


hashTable = (Tcl_HashTable x) 
malloc(sizeof(Tcl_HashTable)); 
Tcl_InitHashTable(hashTable, TCL _STRING_KEYS); 


// Get a hash Entry for the key, and confirm it is a 
// new key 


firstEntry = Tcl_CreateHashEntry(hashTable, key, &isNew); 
if (isNew == 0) { 


printf("Bad key - this key already exists!"); 
return; 


// Define the value for this entry. 


Tcl_SetHashValue(firstEntry, insertData); 


x At this point, the data has been placed in the hash 
le. In an actual application, these sections of 
* code would be in separate functions. 


* 
ee 
ro¥) 

on 


// Retrieve the hash entry with the key. 

secondEntry = Tcl_FindHashEntry(hashTable, key); 
if (secondEntry == (Tcl_HashEntry *) NULL) { 
printf("Failed to find %s\n", key); 
return; 

// Extract the data from the hash entry 

retrievedData = (char *)Tcl_GetHashValue(secondEntry) ; 


// Display the data, just to prove a point 


printf("Retrieved this string from hashTable: \n’%s\n", 
retrievedData); 


Script Output 


Retrieved this string from hashTable: 


This is data in the hash table 
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5.2 BUILDING AN EXTENSION 


The bulk of your extension may be a library of code that has already been developed and tested, a 
library you need to test and validate, or a set of code you will write for this specific extension. In each 
of these cases, you will use the functions described previously to connect the application code to the 
interpreter. The next step is the mechanics of constructing the extension. 


Structural Overview of an Extension 


An extension consists of one or more source code files, one or more include files, and a Make- 
file or VC++, Borland, or CodeWarrior Project files. The source code files must contain a function 
with initialization code, and that function must conform to the naming conventions described in 
Section 15.2.2. 

The source code files will include at least one function that adds new commands to the interpreter 
and at least one function to implement the new commands. A common structure is to create two files: 
one with the initialization function that adds the new commands to the interpreter and a second file 
with the functions that implement the new commands. 

All code that uses functions from the Tcl library will need to include tcl .h. The tc] .h file has all 
the function prototypes, /##define, data definitions, and so on required to interact with the Tcl library 
functions. 


15.2.2 Naming Conventions 

There are a few naming conventions involved with writing a Tcl extension. Some of these are required 
in order to interact with the Tcl interpreter, and some are recommended in order to conform to the 
appearance of other Tcl extensions. If you write your extension to conform to the recommended 
standards, it will be easier for your extension to be used and maintained by others. 

These conventions are described in the Tcl/Tk Engineering Manual, and the Tcl Extension 
Architecture (TEA) guide, found on the companion website. They can also be acquired from 
http://www.tcl.tk/doc/. Most of the conventions mentioned in these documents are discussed in this 
chapter, but you should check the source documents for more details. It may save you from having to 
rewrite your code later. 

In the following tables, you should replace the string ExtName with the name of your extension. 
Note the capitalization, which is part of the naming convention. 


Function Names 
The extension initialization function is expected to have a specific name in order for it to be 
automatically found by the Tcl extension loading commands. 

Function Name Description 


ExtName_Init This function is required. It initializes an extension by creat- 
ing any persistent data objects and registering new commands 
with the Tcl interpreter. This entry point is used to initialize 
the extension when a DLL (Dynamic Link Library) or shared 
library is loaded. The capitalization is important. For example, 
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for an extension named ext the Init function would be 
Ext_Init. 

ExtName_AppInit This function is called to initialize a stand-alone tcl sh inter- 
preter with the extension compiled into it. This is not needed 
when you compile a loadable extension. 


extNameCommand_Cmd These entry points are optional, but this is the naming conven- 
tion used for the C code that will be invoked when the command 
command is evaluated by a Tcl script. For example, if the exten- 
sion named ext implements the Tcl command foo, you would 
put the code implementing the foo command in the function 
extFoo_Cmd. 


File Names 
There are certain conventions followed in Tcl to make it easier for other maintainers to work with your 
code. Your extension will still work if you do not follow these guidelines, but consistency is a good 
thing. 
File Names Description 
extNameInt.h This file is required. It will contain the ##include statements, 
itdefine statements, data structure definitions, and function pro- 
totypes that are used by the code in this extension. This is for the 
package’s internal use. This file will be included by all extension 
code files. 


extName.h This file is optional. If your extension includes a library with a C 
interface, the external API definitions should be in this file. 


extName.c This file is recommended. It will contain the C language functions 
that implement the extension. If your extension is small, it may 
also include the ExtName_Init function. 


extName_Init.c This file is optional. If your extension is medium sized, you may 
use a file named like this for the ExtName_Init function, and put 
the functions that implement the extension into the extName.c 
file, or further subdivide the extension as shown in the following. 


extNameCmd.c This file is optional. If the code to interface between Tcl and the C 
code is large, you may want to separate the code that creates the 
new commands in the Tcl interpreter from the extName.c file and 
place that code in a separate file. 


extNameCmdAL.c These files are optional. If you have a truly large extension, it can 

extNameCmdMZ.c make the code easier to follow if you split the functions that imple- 
ment the commands into smaller files. One convention used for 
this is to put the commands that start with the letter A through 
some other letter in one file, and those that start with a character 
after the breakpoint letter in another file. 
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extNameCommand.c These files are optional. If your extension has commands that 
accept a number of subcommands, or if the command is imple- 
mented with several functions, it can make the code easier to 
follow if you split the functions that implement a command into 
a separate file. Thus, the functions that implement command foo 
would be in extFoo.c, whereas those that implement command 
bar would be in extBar.c. 


extName.d11 A file in one of these formats will be created for your extension 
extName.lib when you have completed compiling your extension. 
extName.so The Tcl interpreter will use the extName part of the extension to 
extName.shlb find the default ExtName_Init function. 

extName.s| 


extNameCFM68K. shl 


If you cannot follow this naming convention for the extension loadable library file, you can force the 
Tcl interpreter to find the initialization function by declaring the extension name in the 1 0ad command 
as follows. 


load wrongname.d1l1 myextension 


Not following the naming convention for the extension library will make it impossible to use 
pkg_mkIndex to construct a tcl Index file, but you can build the index line with a text editor if 
necessary. 


Directory Tree 
The Tcl Extension Architecture (TEA) document defines a directory tree for Tcl extensions. Again, you 
do not need to follow these guidelines to make a working extension, but it will be easier to maintain and 
port your package if you follow them. The templates and skeletons included with the TEA materials 
on the companion website (also available at www.tcl.tk) can make writing an extension easier. Your 
extension 

allows simple relative addressing to be used by the makefiles to find the appropriate files. 


%>1sS sources 
myExtension tcl8.6 tk8.6 


The following files should be placed at the top level of your directory. 

README A short discussion of what the package does and what the user may 
expect to find in this directory. 

license The distribution license for this package. Tcl is distributed with the 
Berkeley license, which is very open. You may elect to use the same 
licensing for your extension, the more restrictive GNU Copyleft, or your 
corporation’s license agreement. 

changes A list of changes that have happened in the package. This should tell a 
user what to expect when they upgrade to a new version. 
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There will be several subdirectories under the main directory. These may include the following. 
generic. This directory will contain C source code files that are not platform dependent. The 
extNamelInt.h file and extName_Init.c files, and the files that implement the 
extension functionality, should be here. 


unix Any UNIX-specific files should be in this directory. If there are platform-specific 
functions (perhaps using system libraries), a copy of the functions for the UNIX 
systems should be here. A UNIX-compatible Makefile or configure file should 
be included in this directory. 


win Any MS Windows specific files should be in this directory. An nmake-compatible 
Makefile or the VC++ or Borland project files should be included. 
mac Any Macintosh-specific files should be in this directory. A Mac-specific Makefile 


or CodeWarrior project files should also be included here. 

compat If your extension requires certain library features that may not exist, or are bro- 
ken on some platforms, put source code files that implement the library calls in this 
directory. 

doc The documentation files should be put here. The standard for documenting Tcl pack- 
ages is to use the UNIX nroff macros used with the main Tcl documentation. These 
can be converted to machine-native formats as necessary. 

tests It is good policy to have a set of regression tests to confirm that the package works 
as expected. 

library If your package has Tcl scripts associated with it, they should go here. 


15.3 AN EXAMPLE 

This section constructs a simple extension that will demonstrate the mechanisms discussed in this 
chapter. On the companion website you will find this demo code, and a dummy Tcl Extension kit with 
a Tcl script that will create a skeleton extension similar to the demo extension. This example follows 
the coding standards in the Tcl/Tk Engineering Manual, which is included on the companion website. 
Where the manual does not define a standard, it is noted that this convention is the author’s, not the Tcl 
standard. Otherwise, the naming conventions and so on are those defined by the Tcl community. 

This demo extension does not perform any calculations. It just shows how an extension can be 
constructed and how to acquire and return data using the hash functions. The demo package imple- 
ments one Tcl command and five subcommands. The subcommands are debug, create, get, 
destroy, and set. 


Syntax: demo debug level 
demo debug Sets a static global variable in the C code that turns on or off 
internal debug output. 
level The level to assign to this variable. A value of zero will disable the 
debugging output, and a non-zero value will enable that output. 
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Syntax: demo create key raw_message 
demo create Create a hash table entry. 


key 


The key for this hash table entry. 


raw.message The string to assign to this hash. 


Syntax: demo get key 


demo get 


key 


Retrieves the value of an entry from the hash table and returns the 
string saved with that key. 


The key for the entry to return. 


Syntax: demo destroy key 
demo destroy Deletes an entry in the hash table. 


key 


The key that identifies which entry to delete. 


Syntax: demo set arrayName index Value 


demo set 


arrayName 


index 
Value 


An example of how to set the values in an associative array. It 
sets the requested index to the requested value and sets the index 
alpha of the array to the value NewValue. The index alpha and 
value NewValue are hard-coded in the procedure Demo_SetCmd. 
This subcommand executes the C code equivalent of 


set arrayName( index) Value 

For example, the command 

demo set myArray myIndex "my Value" 

is equivalent to 

set myArray(myIndex) "my Value" 

Both commands will return the string "my Value". 


The name of a Tcl array. It need not exist before calling this 
subcommand. 


An index into the array. This index will have Value assigned to it. 


The value to assign to arrayName(index). 


The demo extension is arranged in the style of a large package with many commands, to show how 
the functionality can be split across files and functions. It consists of the following files. 
demoInt.h This include file has the definitions for the structures used by this exten- 
sion and the function prototypes of the functions defined in demoInit.c, 
demoCmd.c, and demoDemo.c. 


demoInit.c This file contains the Demo_Init function. 


DemoCmd.c_ This file contains the Demo_Cmd function, which is invoked when a demo 
Tcl command is evaluated in a script. 


This file also includes the descriptions of the subcommands associated with 
the demo command. 


demoDemo.c This file contains the functions that implement the demo subcommands. 
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15.3.1 demoInt.h 


The demoInt.h include file will be included by all the source files in the demo extension. It includes 
the version number information for this extension, the include files that will be used by other functions, 
some magic for Microsoft VC++, definition of data structures used by the demo extension, and the 
function prototypes. 


a mm aaa ——@QQuQ@uw 
Example 2 
demol!nt.h 
/* 
* demoInt.h -- 


* Declarations used by the demotcl extension 
* 
*«/ 
iHifndef _DEMOINT 
itdefine _DEMOINT 
/* 
1 
x Declare the #includes that will be used by this extension 
*/ 
#include <tcl.h> 
dinclude <string.h> 
/* 
2 
* Define the version number 
* Note: VERSION is defined as a string, not integer 
*/ 
ifdefine DEMO_VERSION "1.0" 
/* 
3 
* VC++ has an alternate entry point called 
* DI1Main, so we need to rename our entry point. 
*/ 
#if defined(_WIN32_) 
## define WIN32_LEAN_AND_MEAN 
# include <windows.h> 
# undef WIN32_LEAN_AND_MEAN 
it if defined(_MSC_VER) 
## define EXPORT(a,b) _declspec(dllexport) a b 
# define DI1EntryPoint D11Main 
#f else 
it if defined(__BORLANDC__) 
# define EXPORT(a,b) a -export b 
i else 
# define EXPORT(a,b) a b 
## endif 
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# endif 


#felse 


# define EXPORT(a,b) a b 


dendif 


/* 
4 


* 


* 


*/ 
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typedef struct cmd_return { 


int 


status; 


Tcl_Obj xobject; 
} CmdReturn; 


The CmdReturn structure is used by the subroutines to 
pass back a success/failure code and a Tcl_Obj result. 


This is not an official Tcl standard return type. I 
find this works well with commands that accept subcommands 


-Interp *)); 


/* 

5 
* Function Prototypes for the commands that actually do 
* the processing. 
* Two macros are used in these prototypes: 
* 
* EXTERN EXPORT is for functions that must interact with 
* the Microsoft or Borland C++ DLL loader. 
* ANST_ARGS_ is defined in tcl.h 
* ANST_ARGS_ returns an empty string for non-ANSI C 
* compilers, and returns its arguments for ANSI C 
* compilers. 
*/ 

EXTERN EXPORT(int,Demo_Init) _ANSI_ARGS_ ((Tc 

EXTERN EXPORT(int,Demo_Cmd) _ANSI_ARGS_ ((ClientData, 
Tcl_Interp *, int, Tcl_Obj **)); 

CmdReturn *xdemo_GetCmd _ANSI_ARGS. ((ClientData, 
Tcl_Interp *, int, Tcl_Obj **)); 

CmdReturn xdemo_SetCmd _ANSI_ARGS. ((ClientData, 
Tcl_Interp *, int, Tcl_Obj x**)); 

CmdReturn xdemo_CreateCmd _ANSI_ARGS_ ((ClientData, 
Tcl_Interp *, int, Tcl_Obj **)); 

CmdReturn *xdemo_DestroyCmd _ANSI_ARGS. ((ClientData, 

Tcl_Interp *, int, Tcl_Obj **)); 

void demo_InitHashTable _ANSI_ARGS_ (()); 

/x* 

* For debugging printf’s. 

*«/ 


##tdefine debugprt if (demoDebugPrint>0) printf 
/x End _DEMOINT x/ 
#fendif 
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Note the following regarding the previous example. 


1. The demoInt.h file has the #include definitions that will be used by the source code files in 
the demo package. If the extension requires several include files, this convention makes it easier to 
maintain the list of include files. 

2. The DEMO_VERSION string will be used in the Demo_Init function to define the script global vari- 
able demo_version. All packages should include a packageName_version variable definition. 
Defining this variable allows scripts to check the version of the package they have loaded. 

3. There are some conventions that Microsoft VC++ demands for code that will be dynamically 
loaded. If your extension will need to compile only on UNIX or Macintosh, you may delete this 
section and simplify the function prototypes. 

4. The CmdReturn structure is not a part of the Tcl standard. I use it to allow functions that implement 
subcommands to return both a status and a Tc1_0bj to the function that implements the primary 
command. The status field will be assigned the value TCL_OK or TCL_ERROR. The object field 
will be a pointer to a Tcl Object, or NULL if the function has no return. If you find another convention 
more suited to your needs, feel free to use that instead. 

5. These are the function prototypes. All of the functions in the source code files should be 
declared here. 


demolInit.c 


The demoInit.c file is one of the required files in an extension. At a minimum this file must define 
the Demo_Init function, as shown in the following example. 


Oooo —n—n—n—n— Oey»: >= 
Example 3 


demolnit.c 
d#finclude "demoInt.h" 
/* CVS Revision Tag */ 
i#tdefine DEMOINIT_REVISION "$Revision: 1.5 $" 
/* 
* * 


* Demo_Init 


* Called from demo-AppInit() if this is a standalone 
* shell, or when the package is loaded if compiled 
* into a binary package. 


* Results: 
* A standard Tcl result. 


* Side effects: 

* Creates a hash table. 

* Adds new commands 

* Creates new Tcl global variables for demo_version and 
* demoInit-revision. 
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* x/ 
int Demo_Init(Tcl_Interp xinterp) { 
/* interp Current interpreter. */ 


« If this application will need to save any 
* data in a hash table initialize the hash table. 
*/ 
Demo_InitHashTable (); 
/* 
2 
* Call Tcl_CreateCommand for commands defined by this 
* extension 
*/ 
Tcl_-CreateObjCommand(interp, "demo", Demo_Cmd, 
(ClientData) NULL, NULL); 
/* 
3 
x Define the package for pkg_mkIndex to index 
*/ 
Tcl_PkgProvide(interp, "demo", DEMO_VERSION); 
/* 
4 
x Define the version for this package 
*/ 
Tcl_SetVar((Tcl_Interp *) interp, "demo_version", 
DEMO_LVERSION, TCL_GLOBAL_ONLY ) ; 
/* 
5 
* Not a requirement. I like to make the source code 
* revision available as a Tcl variable. 
* It’s easier to track bugs when you can track all the 
* revisions of all the files in a release. 
*/ 
Tcl_SetVar((Tcl_Interp *) interp, "demoInit_revision", 
DEMOINIT-REVISION, TCL-GLOBAL_ONLY ) ; 
/* 
6 
*/ 
return TCL_OK; 


Note the following regarding the previous example. 


1. Tcl allows any package to create its own hash table database to store and retrieve arbitrary data. If a 
package needs to share persistent information with scripts, you will probably need to save that data 


15.3 An Example 595 


in a hash table and return a key to the script to identify which data is being referenced. The hash 
table is discussed in more detail with the functions that actually interact with the table. 

2. The Tcl_Create0bjCommand function creates a Tcl command demo and declares that the function 
Demo_Cmd is to be called when this command is evaluated. 

3. The Tcl_PkgProvide command declares that this package is named demo, and the revision defined 
by DEMO_VERSION. DEMO_VERSION is #defined in demoInt.h. 

4. This Tc]_SetVar command defines a global Tcl variable demo_version as the version number of 
this package. This definition allows a script to check the version number of the demo package that 
was loaded. 

5. This is not part of the Tcl standard. My preference is to include the source control revision string 
in each module to make it easy to determine just what versions of all the code were linked into 
a package. This is particularly important when in a crunch phase of a project and making several 
releases a day to testers who are trying to convey what behavior was seen on what version of 
the code. 

6. Finally, return TCL_OK. None of these function calls should fail. 


15.3.3 demoCmd.c 


The demoCmd.c file is where most of your extension code will exist. For small extensions, this file will 
contain all of the code that implements your package functionality. The Demo_Cmd function introduces 
a couple of new Tcl library functions. 

The Tcl_GetIndexFrom0bj function searches a list of words for a target word. This function will 
return the index of the word that either exactly matches the target word or is a unique abbreviation 
of the target word. This function is used in this example to extract a subcommand from a list of valid 
subcommands. 


Syntax: int Tcl_GetIndexFrom0Obj (interp, objPtr, tbiPtr, msg, flags, 
indexPtr) 
Tcl_GetIndexFrom0bj sets the variable pointed to by indexPtr to the offset into 
tablePtr of the entry that matches the string representation of the data in objPtr. An 
item in tab/ePtr is defined as a match if it is either an exact match to a string in the 
table or a unique abbreviation for a string in the table. This function returns TCL_OK if 
it finds a match or TCL_ERROR if no match is found. If Tc]_GetIndexFrom0bj fails, 
it will set an error message in the interpreter’s result object. 
interp A pointer to the Tcl interpreter. 
tablePtr A pointer to a NULL-terminated list of strings to be searched for a match. 
msg A string that will be included in an error message to explain what was 
being looked up if Tc]_Get IndexFrom0bj fails. The error message will 
resemble the following. 
bad msg "string": must be tableStrings 
msg The string defined in the msg argument. 
string The string representation of the data in objPtr. 
tableStrings The strings defined in tablePtr. 
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flags The flags argument allows the calling code to define what matches 
are acceptable. If this flag is TCL_EXACT, only exact matches will 
be returned, rather than allowing abbreviations. 


indexPtr A pointer to the integer that will receive the index of the matching 
field. 


The demoCmd.c file contains the C functions that are called when demo commands are evaluated in 
the Tcl script. In a larger package with several commands, this file would contain several entry points. 


Sl — 
Example 4 
demoCmd.c 

dFinclude "demoInt.h" 


/* 


Define the subcommands 


These strings define the subcommands that the demo command 
supports. 


* 

* 

* 

* 

* 

* To add a new subcommand, add the new subcommand string, 
* #define, and entry in cmdDefinition. 
* 
* 
* 
* 
* 
* 


Note: Order is important. 


These are the subcommands that will be recognized 


static char *subcommands[] = { 
"create", "set", "get", "debug", "destroy", NULL}; 


/* 


x These #defines define the positions of the subcommands. 
* You can use enum if you are certain your compiler will 
* provide the same numbers as this. 

*/ 


ifdefine M_create 0 
itdefine M_set 1 
itdefine M_get 2 
ifdefine M_debug 3 
ifdefine M_destroy 4 


/* 
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The cmdDefinition structure describes the minimum and 
maximum number of expected arguments for the subcommand 
(including cmd and subcommand names), and a usage message 
to return if the argument count is outside the expected 
range. 


+ + F F F 


typedef struct cmd_Def { 
char x*usage; 
int minArgCnt; 
int maxArgCnt; 
} cmdDefinition; 


static cmd_Def definitions[5] = { 
{"create key raw_message", 4 , 4}, 

{"set arrayName index Value", 5, 5}, 

{"get key ", 3, 3}, 

{"debug level", 3, 3}, 

{"destroy key", 3,3} 


/* 


* If demoDebugPrint != 0, then debugprt will print debugging 
* info. This value is set with the subcommand debug. 
*/ 


int demoDebugPrint = 0; 


/* 

BN a Me na BAD htc fa ea ha ae ty oy uy Rte MEN LL 
* 

x Demo_Cmd -- 

* 

* Demo_Cmd is invoked to process the "demo" Tcl command. 
* It will parse a subcommand, and perform the requested 
* action. 

* 

x Results: 

x A standard Tcl result. 

* 

x Side effects: 

* 
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int Demo_Cmd(ClientData demo, 
Tcl_Interp *interp, 

int objc, 

Tcl_Obj *xobjvl]) { 

/* ClientData demo; 


/* Not used. */ 


/* Tcl_Interp *interp; /x Current interpreter. x/ 
/x int objec; /x Number of arguments. x/ 
/* Tcl_Obj *CONST objv£J; /* Argument objects. */ 


int cmdnum; 
int result; 
Tcl_Obj *returnValue; 
CmdReturn *returnStruct; 
ClientData info; 


/* 
* Initialize the return value 
*/ 


returnValue = NULL; 
returnStruct = NULL; 


list of subcommands. 


/* 
6 
* Check that we have at least a subcommand, 
* else return an Error and the usage message 
*/ 
if (objec < 2) { 
Tcl_WrongNumArgs(interp, 1, objv, 
"subcommand ?options?"); 
return TCL_ERROR; 
} 
/* 
7 
* Find this demo subcommand in the 
* Tcl_GetIndexFrom0bj returns the offset of the recognized 
* string, which is used to index into the command 
* definitions table. 
x / 


result = Tcl_GetIndexFrom0bj(interp, 


objvL1], subcommands, 


"subcommand", TCL_EXACT, &cmdnum) ; 
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x If the result is not TCL_OK, then the error message is 
* already in the Tcl Interpreter, this code can 
* immediately return. 


*/ 


if (result != TCL_OK) { 
return TCL_ERROR; 


/* 


* Check that the argument count matches what’s expected 
* for this Subcommand. 


*/ 


if (Cobjc < definitions[cmdnum].minArgCnt) | 


(objec > definitionsLcmdnum].maxArgCnt) ) { 
Tcl_WrongNumArgs(interp, 1, objv, 


definitions[cmdnum].usage); 


return TCL_ERROR; 


result 


/* 


10 
x The 


= TCL_OK; 


subcommand is recognized, and has a valid number of 


* arguments Process the command. 


*/ 


switch 
case 


case 


(cmdnum) { 
M_debug: { 
char xtmp; 
tmp = Tcl_GetStringFrom0bj(objv£2], NULL); 
if (TCL_OK != 
Tcl_GetInt(interp, tmp, &demoDebugPrint)) { 
return (TCL_ERROR); 
} 
break; 


M_destroy: { 
returnStruct = 
Demo_DestroyCmd((ClientData) &info, 
interp, objc, objv); 
break; 
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} 


case M_create: { 


} 


returnStruct = 
Demo_CreateCmd((ClientData) &info, 
interp, objc, objv); 
break; 


case M_get: { 


} 


returnStruct = 
Demo_GetCmd((ClientData) &info, 
interp, objc, objv); 
break; 


case M_set: { 


} 


returnStruct = 
Demo_SetCmd((ClientData) &info, 
interp, objc, objv); 
break; 


default: { 


char error[80]; 
sprintf(Cerror, 
"Bad sub-command %s. Has no switch entry", 
Tcl_GetStringFrom0bj(objv£1]J, NULL)); 
returnValue = Tcl_NewStringObj(error, -1); 
result = TCL_ERROR; 


/* 
11 
* Extract an object to return from returnStruct. 
* returnStruct will be NULL if the processing is done 
* in this function and no other function is called. 
*/ 
if CreturnStruct != NULL) { 
returnValue = returnStruct->object; 
result = returnStruct->status; 
free (returnStruct); 
} 
/* 
12 


* Set the return value and return the status 


*/ 
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if (returnValue != NULL) { 
Tcl_SetObjResult(interp, returnValue); 

} 

return result; 

} 


Note the following regarding the previous script example. 


1. The subcommands array of strings will be passed to the Tcl_GetIndexFrom0bj function that 
will identify a valid subcommand from this list. 

2. These #defines create a set of textual identifiers for the positions of the subcommands in the 
list. They will be used in a switch command in the main code to select which function to call to 
implement the subcommands. 

3. The cmdDef structure is not part of the official Tcl coding standards. It is strongly recommended 
that functions check their arguments and return a usage message if the arguments do not at least 
match the expected count. This can be done in each function that implements a subcommand, or in 
the function that implements the main command. I prefer to use this table to define the maximum 
and minimum number of arguments expected and the error message to return if the number of 
arguments received is not within that range. 

4. There is a ##define macro used to define debugprt in demoInt.h. This will reference the 
demoDebugPrint global variable. This is not part of the official Tcl coding standards. I find 
it convenient to use printf for some levels of debugging. 

5. This is the standard header for a C function in a Tcl extension, as recommended in the Tcl/Tk 
Engineering Manual. 

6. If there are not at least two arguments, this command was not called with the required 
subcommand argument. 

7. The Tcl_GetIndexFromO0bj call will set the cmdnum variable to the index of the subcommand 
in the list, if there is a match. 

8. If the Tcl_GetIndexFrom0bj call returned TCL_ERROR, it will have set an error return as a side 
effect. If the return value is not TCL_OK, this function can perform any required cleanup and return 
a TCL_ERROR status. The interface with Tcl interpreter is already taken care of. 

9. This section of code is not part of the official Tcl coding standard. The tests can be done 
here or in the individual functions that will be called from the switch statement. The call to 
Tcl_WrongNumArgs sets the return value for this function to a standard error message and leaves 
the interface with the interpreter ready for this function return. 

10. When the execution has reached this point, all syntactical checks have been completed. The sub- 
command processing can be done in this function, as is done for the demo debug command, or 
another function can be called, as is done for the other subcommands. 

The functions that implement the commands are named using the naming convention 
Demo_subcommand Cmd. 

Note that this switch statement does not require a default case statement. This code will be 
evaluated only if the Tcl_GetIndexFromObj function returned a valid index. This code should 
not be called with an unexpected value in normal operation. 


602 CHAPTER 15 Extending Tcl 


However, most code will require maintenance at some point in its life cycle. If anew command 
were added, the tables updated, and the switch statement not changed, a silent error could be 
introduced to the extension. Including the default case protects against that failure mode. 

11. The CmdReturn structure is not part of the official Tcl coding style. I find it useful to return both 
status and an object from a function, and this works. You may prefer to transfer the status and 
object with C variables passed as pointers in the function argument list. 

12. The returnValue is tracked separately from the returnStruct so that subcommands pro- 
cessed within this function as well as external functions can set the integer result code and 
returnStruct object to return values to the calling script. 


3.4 demoDemo.c 


The demoDemo.c file has the functions that implement the subcommands of the demo command. The 
naming convention is that the first demo indicates this is part of the demo package, and the second 
demo indicates that this file implements the demo command. If there were a foo command in this 
demo package, it would be implemented in the file demoFoo.c. 

Most of these functions will be called from demoCmd.c. The exception is the 
Demo_InitHashTable function, which is called from Demo_Init. This function is included in 
this file to allow the hash table pointer (demo_hashtb1) to bea static global and keep all references 
to it within this file. 


Demo_InitHashTable 
This function simply initializes the Tcl hash table and defines the keys to be NULL -terminated 
strings. 


———ooooooo OO —-n—n—n—n— —e—eeeeeeeeeeeeeeeeeeOEe 
Example 5 


Demo_InitHashTable 
dFinclude "demoInt.h" 


static Tcl_HashTable *demo_hashtb1Ptr; 


extern int demoDebugPrint; 


[*----- 7-7 - rr cree rr 2-5-2 - 2-2-2 - 2-2 - --------- 
* void Demo_InitHashTable ()-- 

* Initialize a hash table. 

* If your application does not need a hash table, this may be 
* deleted. 

* 

* Arguments 

* NONE 

* 

* Results 

* Initializes the hash table to accept STRING keys 
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* 
* Side Effects: 
x None 


void Demo_InitHashTable () { 
demo_hashtb1Ptr = (Tcl_HashTable x) 
malloc(sizeof(Tcl_HashTable)); 
Tcl_InitHashTable(demo_hashtbIPtr, TCL_STRING_KEYS); 


Demo_CreateCmd 

This function implements the create subcommand. Demo_CreateCmd is the first function we have 
discussed that checks arguments for more than syntactic correctness and needs to return status 
messages other than syntax messages provided by the Tcl interpreter. 

This function uses both the Tcl_AddObjErrorInfo and the Tcl_AddErrorInfo function to 
demonstrate how each can be used. The error messages are appended to the return value for 
Demo_CreateCmd in the order in which the error functions are called. 

The Tcl_SetErrorCode function concatenates the string arguments into the Tcl script global 
variable errorCode. It adds spaces as required to maintain the arguments as separate words in the 
errorCode variable. 


EB 


Example 6 
Demo_CreateCmd 
[k---- 7-7-7 err eo------ 2-2-2 ee eee 5-5 --- 5 -------- 
* CmdReturn xDemo_CreateCmd ()-- 
* Demonstrates creating a hash entry. 
* Creates a hash entry for Key, with value String 
* Arguments 
* objv[0]: "demo" 
* objv[l]: "create" 
* objv[2]: hash Key 
* objvl3]: String 
* 
* Results 
* Creates a new hash entry. Sets error if entry already 
* exists. 
* 
x Side Effects: 
* None 


CmdReturn *Demo_CreateCmd (ClientData info, 
Tcl_Interp xinterp, 
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int objc, 

Tcl_Obj xobjvlJ) { 
Tcl_HashEntry *hashEntryPtr; 
CmdReturn xreturnStructPtr; 
char xreturnCharPtr; 
char *tmpString; 

Tcl_Obj *returnObjPtr; 
char xhashEntryContentsPtr; 
char *hashKkeyPtr; 


int isNew; 
int length; 
/* 
1 
* Print that the function was called for debugging 
*/ 
debugprt("Demo_CreateCmd called with 4d args\n", objc); 
/* 
2 
* Allocate the space and initialize the return structure. 
*/ 
returnStructPtr = (CmdReturn *) malloc(sizeof (CmdReturn)); 
returnStructPtr->status = TCL_OK; 
returnCharPtr = NULL; 
returnObjPtr = NULL; 
/* 
3 
* Extract the string representation of the object 
* argument, and use that as a key into the hash table. 
* 
x If this entry already exists, complain. 
*/ 


hashKeyPtr = Tcl_GetStringFrom0bj(objv£2], NULL); 
hashEntryPtr = Tcl_CreateHashEntry(demo_hashtb1Ptr, 
hashKeyPtr, &isNew); 


if (!isNew) 
char errString[80]; 


sprintfCerrString, 
"Hashed object named \"%s\" already exists.\n", 


hashKeyPtr); 


/* 
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* Both of these strings will be added to the Tcl script 


* global variable errorInfo 
*/ 


Tcl_AddErrorInfo(interp, "error in Demo_CreateCmd") ; 


Tcl_AddObjErrorInfo(interp, errString, 
strlen(errString)); 


/* 


* This SetErrorCode command will set the Tcl script 
* variable errorCode to "APPLICATION" "Name in use" 
*/ 


Tcl_SetErrorCode(interp, "APPLICATION", \ 
"Name in use", (char *) NULL); 


/* 
* This defines the return string for this subcommand 
*«/ 


Tcl_AppendResult(interp, "Hashed object named \"", 
hashKeyPtr, "\" already exists.", (char *) NULL) 


returnStructPtr->status = TCL_ERROR; 


goto done; 


+ 


If we are here, then the key is unused. 
Get the string representation from the object, 


+ 


* and make a copy that can be placed into the hash table. 


*/ 


tmpString = Tcl_GetStringFrom0bj(objv[3], &length); 
hashEntryContentsPtr = (char *) malloc(length+1); 
strcpy(hashEntryContentsPtr, tmpString) ; 
debugprt("setting: %s\n", hashEntryContentsPtr) ; 
Tcl_SetHashValue(hashEntryPtr, hashEntryContentsPtr); 


/* 


* Set the return values, cleanup and return 
*/ 
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done: 
if (CreturnObjPtr == NULL) && (returnCharPtr != NULL)) { 
returnObjPtr = Tcl_NewStringObj(returnCharPtr, -1); 
} 
returnStructPtr->object = returnObjPtr; 
if (returnCharPtr != NULL) {free(CreturnCharPtr) ; } 
return returnStructPtr; 


} 
rt 


Note the following in regard to the previous example. 


1. 


This is not a part of the Tcl standard. I find that in many circumstances I need to generate execution 
traces to track down the types of bugs that show up once every three weeks of continuous operation. 
Real-time debuggers are not always appropriate for this type of problem, whereas log files may help 
pinpoint the problem. I like to be able to enable an output message whenever a function is entered. 


. The returnStructPtr is initialized in each of the functions that process the subcommands. It 


will be freed in the Demo_Cmd function after this function returns. 


. If the hashKeyPtr already exists, isNew will be set to zero, and a pointer to the pre- 


vious hashEntryPtr will be returned. If your code sets the value of this entry with a 
Tcl_SetHashValue call, the old data will be lost. 

Note that the sprintf call in this example is error prone. If the key is more than 37 characters, 
it will overflow the 80 characters allocated for errString . A robust application would count the 
characters, allocate space for the string, invoke Tcl_AddError to copy the error message to the 
error return, and then free the string. 


. Each time Tcl_AddError or Tcl_AddObjError is called, it will append the argument, followed 


by a new! ine character to the end of the global script variable error Info. 
The Tcl_SetErrorCode function treats each string as a separate list element. The first field should 
be a label that will define the format of the following data. 


. Note that the string data in the third argument to the create subcommand is copied to another area 


of memory before being inserted into the hash table. The argument object is a temporary object that 
will be destroyed, along with its data, when the demo create command is fully evaluated. 

The Tcl_HashEntry structure accepts a pointer as the data to store. It retains the pointer, 
rather than copying the data to a new place. Thus, if the string pointer returned from the 
Tcl_GetStringFrom0bj(objv[3],... call were used as the data in the Tcl_SetHashValue 
call, the string would be destroyed when the command completed, and the data in those memory 
locations could become corrupted. 


. All of the functions that implement the demo subcommands use a flow model of testing values, 


setting failure values if necessary, and using a goto to exit the function. This can also be done 
using a structured programming flow, but becomes complex and difficult to follow when there are 
multiple tests. 


Demo_GetCmd 
The Demo_GetCmd will return the string that was inserted into the hash table with a demo create 
command. This function follows the same flow as the Demo_CreateCmd function 
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Example 7 
Demo_GetCmd 


* CmdReturn *Demo_GetCmd ()-- 
Demonstrates retrieving a value from a hash table. 
Returns the value of the requested item in the hash table 


Arguments 
objvl0]: "demo" 
objvLl]: "get" 
jvl2]: hash Key 


Results 
No changes to hash table. Returns saved value, or sets error. 


Side Effects: 


+ F F F F F FF F F F F F 
© 
a 


CmdReturn *Demo_GetCmd (ClientData info, 
Tcl_Interp xinterp, 
int objc, 
Tcel_Obj *objvlJ) { 
Tcl_HashEntry xhashEntryPtr; 
CmdReturn xreturnStructPtr; 
char *returnCharPtr; 
Tcl_Obj *returnObjPtr; 
char xhashKkeyPtr; 
debugprt("Demo_GetCmd called with %d args\n", objc); 


/* 
x Allocate the space and initialize the return structure. 
*/ 


returnStructPtr = (CmdReturn *) malloc(sizeof (CmdReturn)); 


returnStructPtr->status 
returnStructPtr->object 
returnCharPtr = NULL; 
returnObjPtr = NULL; 


TCL_OK; 
NULL; 


* Get the key from the argument 


* and attempt to extract that entry from the hashtable. 
x If the returned entry pointer is NULL, this key is not in 
* the table. 
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hashkKeyPtr = Tcl_GetStringFrom0bj(objv£2], NULL); 
hashEntryPtr = 
Tcl_FindHashEntry(demo_hashtb1]Ptr, hashKeyPtr); 


if (hashEntryPtr == (Tcl_HashEntry *) NULL) 
char errStringL80]; 
Tcl_Obj *xobjvl2]; 
Tcl_Obj *xerrCodePtr; 


/* 
1 

* Define an error code as a list. Set errorCode. 
*/ 

objvl0] = Tcl_NewStringObj( "APPLICATION", -1); 
objv£1] = Tcl_NewStringObj("No such name", -1); 
errCodePtr = Tcl_NewListObj(2, objv); 

/* 

* This string will be placed in the global variable 
* errorinfo 

*/ 

sprintfCerrString, 

"Hash object \"%s\" does not exist.", hashKeyPtr); 

Tcl_AddErrorInfo(interp, errString); 

/* 

* This string will be returned as the result of the 
* command. 

*/ 

Tcl_AppendResult(interp, 

"can not find hashed object named \"", 
hashKeyPtr, "\"", (char *) NULL); 

returnStructPtr->status = TCL_ERROR; 

goto done; 

} 
/* 
2 


* If we got here, then the search was successful and we can 
* extract the data value from the hash entry and return it. 
*/ 


returnCharPtr = (char *)Tcl_GetHashValue(hashEntryPtr) ; 
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debugprt("returnString: %s\n", returnCharPtr) ; 


done: 
if ((returnObjPtr == NULL) && (returnCharPtr != NULL)) { 
returnObjPtr = Tcl_NewStringObj(returnCharPtr, -1); 


returnStructPtr->object = returnObjPtr; 
if (returnCharPtr != NULL) {free(returnCharPtr) ; } 
return returnStructPtr; 


Note the following in regard to the previous example. 


1. Demo_GetCmd uses the Tcl_SetObjErrorCode function to set the global script variable error - 
Code. This function assigns the errCodePtr to the error code. It does not make a copy of the 
object. 

2. The character pointer returnCharPtr will be set to point to the string that was stored in the hash 
table. This is not a copy of the data. The data is copied when returnObjPtr is created with the 
Tcl_NewStringObj(returnCharPtr, -1) function. 


Demo_DestroyCmd 

The Demo_DestroyCmd function will remove an item from the hash table and release the memory 
associated with it. This example uses yet another technique for setting the error returns. The default 
behavior is to set the global script variable error Info with the same string as the function return and 
to set the errorCode value to NONE. This function simply allows that to happen. 


——————— eee eee 
Example 8 


Demo_DestroyCmd 


* CmdReturn *Demo_DestroyCmd ()-- 


associated with the hash object being stored. 


Side Effects: 
None 


* Demonstrate destroying an entry in the hash table. 
* Arguments 

* objv[0]: "demo" 

* objv[l]: "destroy" 

* objv[2]: hash Key 

* 

* Results 

* Deletes the hash table entry and frees the memory 
* 

* 

* 

* 
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CmdReturn *xDemo_DestroyCmd (ClientData info, 
Tcl_Interp xinterp, 
int objc, 
Tcl_Obj xobjvlJ) { 
Tcl_HashEntry *xhashEntryPtr; 
CmdReturn *returnStructPtr; 
char xreturnCharPtr; 
Tcl_Obj *returnObjPtr; 
char *hashEntryContentsPtr; 
char *hashKeyPtr; 
debugprt("Demo_DestroyCmd called with 4d args\n", objc); 


/* 

* Allocate the space and initialize the return structure. 
*/ 
returnStructPtr = (CmdReturn *) malloc(sizeof (CmdReturn) ); 


returnStructPtr->status = TCL_OK; 
returnStructPtr->object NULL; 
returnCharPtr = NULL; 
returnObjPtr NULL; 


/* 

* Extract the string representation from the argument, and 
* use it as a key into the hash table. 

*/ 


hashkKeyPtr = Tcl_GetStringFrom0bj(objv£2], NULL); 
hashEntryPtr = Tcl_FindHashEntry(demo_hashtb1Ptr, 
hashKeyPtr) ; 


/* 


* If the hashEntryPtr returns NULL, then this key is not in 
* the table. Return an error. 
*/ 


if (hashEntryPtr == (Tcl_HashEntry *) NULL) 
/* 

* Tcl_AppendResult sets the return for this command. 
The script global variable errorInfo will also be 
set to this string. 

The script global variable errorCode will be set to 
"NONE" 


+ + + > 


Tcl_AppendResult(interp, 
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"cannot find hashed object named \"", 
hashkeyPtr, "\"", (char *) NULL) 
returnStructPtr->status = TCL_ERROR; 
goto done; 


/* 


x Retrieve the pointer to the data saved in the hash table 
* and free it. Then delete the hash table entry. 
*/ 


hashEntryContentsPtr = 
(char *)Tcl_GetHashValue(hashEntryPtr) ; 
free(hashEntryContentsPtr) ; 


Tcl_DeleteHashEntry(hashEntryPtr) ; 


done: 


if ((returnObjPtr == NULL) && (returnCharPtr != NULL)) { 
returnObjPtr = Tcl_NewStringObj(returnCharPtr, -1); 

} 

returnStructPtr->object = returnObjPtr; 


if CreturnCharPtr != NULL) {free(returnCharPtr) ;} 


return returnStructPtr; 


Note the following in regard to the previous example. 


1. 


This function allows the interpreter to set the error Info and errorCode values. The string can- 


not find hashed object... will be returned as the result of the command and will also be 


placed in the error Info variable. 
The data saved in the hash table is the pointer to the string that was created in the Demo_CreateCmd 
function. Once the Tcl_HashEntry pointer is destroyed, that pointer will be an orphan unless there 
is other code that references it. In this example, there is no other code using the pointer, so the 
memory must be released. 


Demo_SetCmd 
The Demo_SetCmd demonstrates creating or modifying an array variable in the calling script. By 
default, the variable will be set in the scope of the command that calls the demo set command. If 


612 CHAPTER 15 Extending Tcl 


demo set is called from within a procedure, the variable will exist only while that procedure is being 
evaluated. The Tcl interpreter will take care of releasing the variable when the procedure completes. 

Demo_SetCmd uses the Tcl_ObjSetVar2 function to set the value of the array variable. The 
Tcl_ObjSetVar2 and Tcl_ObjGetVar2 functions allow C code to get or set the value of a Tcl script 
variable. Tc]l_ObjSetVar2 and Tcl_ObjGetVar2 are the functions called by the Tcl interpreter to 
access variables in a script. Any behavior the Tcl interpreter supports for scripts is also supported for 
C code that is using these functions. You can modify the behavior of these commands with the flags 
argument. By default, the behavior is as follows. 


e When accessing an existing variable, the Tc1_ObjGetVar2 command first tries to find a variable in 
the local procedure scope. If that fails, it looks for a variable defined with the variable command 
in the current namespace. Finally, it looks in the global scope. 

e The Tcl_0bjSetVar2 function will overwrite the existing value of a variable by default. The 
default is not to append the new data to an existing variable. 

e When referencing an array, the array name and index are referenced in separate objects. By default, 
you cannot reference an array item with an object that has a string representation of name (index). 


Syntax: char *Tcl_SetVar2(interp, namel, name2, newstring, flags) 


Syntax: char *«Tcl_GetVar2(interp, name2, namel, flags) 

Tcl_SetVar2 Creates or modifies a script variable. The value of value of 
the referenced variable will be set to newstring. This 
function returns a char * pointer to the new value. This 
function is for use with versions of Tcl older than 8.0. 

Tcl_GetVar2 Returns the string value for the variable or array reference 
identified by the string values in namel and name2. This 
function is for use with versions of Tcl older than 8.0. 


Tcl_Interp *interp A pointer to the Tcl interpreter. 


char *namel A string that references either a simple Tcl string variable or 
the name of an associative array. 

char *xname2 If this is not NULL; it is the index of an array variable. If 
this is not NULL, name1 must contain the name of an array 
variable. 

char *newstring A string that contains the new value to be assigned to the 


variable described by name1 and name2. 


int flags The f]ags parameter can be used to tune the behavior of 

these commands. The value of f1ags is a bitmap composed 

of the logical OR of the following fields: 

TCL_GLOBAL_ONLY 

Setting this flag causes the variable name to be referenced 
only in the global scope, not a namespace or local 


procedure scope. If both this and the 
TCL_NAMESPACE_ONLY flags are set, this flag is ignored. 
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TCL_NAMESPACE_ONLY 

Setting this flag causes the variable to be referenced only in 
the current namespace scope, not in the current local 
procedure scope. This flag overrides TCL_GLOBAL_ONLY. 

TCL_LEAVE_ERR_MSG 

This flag causes an error message to be placed in the 
interpreter’s result object if the command fails. If this is 
not set, no error message will be left. 

TCL_APPEND_VALUE 


If this flag is set, the new value will be appended to the 

existing value, instead of overwriting it. 

TCL_LIST_ELEMENT 

If this flag is set, the new data will be converted into a valid 
list element before being appended to the existing data. 

TCL_PARSE_PART1 

If this flag is set and the id1Ptr object contains a string 

defining an array element (arrayName (index )), this will 

be used to reference the array index, rather than using the 

value in jd2Ptr as the index. 


Syntax: Tcl_0bj *Tcl_ObjSetVar2(interp, idlPtr, id2Ptr, newValPtr, flags) 


Syntax: Tcl_Obj *Tcl_ObjGetVar2(interp, idiPtr, id2Ptr, flags) 
Tcl_ObjSetVar2 Creates or modifies a Tcl variable. The value of the 

referenced variable will be set to the value of the 
newValPtr object. The Tc1_Obj pointer will be a pointer 
to the new object. This may not be a pointer to newVal Ptr 
if events triggered by accessing the newValPtr modify the 
content of newValPtr. This can occur if you are using the 
trace command to observe a variable. See the discussion 
on using trace in Section 16.1 and read about the trace 
command in your on-line help to see how this can happen. 


Tcl_ObjGetVar2 Returns a Tcl object containing a value for the variable 
identified by the string values in 7d1Ptr and id2Ptr. 

Tcl_Interp *interp A pointer to the Tcl interpreter. 

Tcl_Obj *idi1Ptr An object that contains the name of a Tcl variable. This 
may be either a simple variable or an array name. 

Tcl_Obj xid2Ptr If this is not NULL, it contains the index of an array variable. 
If this is not NULL, 7d1Ptr must contain the name of an 
array variable. 

Tcl_0bj *newValPtr A pointer to an object with the new value to be assigned to 


the variable described by id1Ptr and id2Ptr. 
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int flags The f]ags parameter can be used to tune the behavior of 
these commands. The value of f1ags is a bitmap composed 
of the logical OR of the fields described for Tc1_SetVar2 
and Tcl_GetVar2. 


ooo —_:——nmn— a -Ee 
Example 9 


Demo_SetCmd 


* CmdReturn *Demo_SetCmd ()-- 

Demonstrates setting an array to a value 
Arguments 

objvlL0]: "demo" 

objv[l]J: "set" 

objv£[2]: arrayName 

objv£3]: Index 

objv[4]: Value 


Results 

Sets arrayName(Index) to the Value 

Also sets arrayName(alpha) to the string "NewValue". 
Returns the string "NewValue" 


Side Effects: 
None 


CmdReturn *xDemo_SetCmd (ClientData info, 

Tcl_Interp xinterp, 

int objc, 

Tcl_Obj xobjv£J) { 

Tcl_Obj *returnObjPtr; 

Tcl_Obj *indexObjPtr; 

Tcl_Obj *xarrayObjPtr; 

Tcl_Obj *valueObjPtr; 

CmdReturn *returnStructPtr; 

debugprt("Demo_SetCmd called with 4d args\n", objc); 
/* 
* Allocate the space and initialize the return structure. 
*/ 

returnStructPtr = (CmdReturn *) malloc(sizeof (CmdReturn) ); 
returnStructPtr->status = TCL_OK; 

returnObjPtr = NULL; 


/* 


* Use Tcl_ObjSetVar2 to set the array element "Index" to 
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* "Value" 

*/ 

arrayObjPtr = objv[2]; 

Tcl_ObjSetVar2(interp, arrayObjPtr, objv[3], objvl[4], 0); 


/* 


x Create two new objects to set a value for index "alpha" 
* jn the array. 
*/ 


indexObjPtr = Tcl_NewStringObj("alpha", -1); 
valueObjPtr Tcl_NewStringObj("NewValue", -1); 


returnObjPtr = Tcl_ObjSetVar2(interp, arrayObjPtr, 
indexObjPtr, valueObjPtr, 0); 

returnStructPtr->status = TCL_OK; 

returnStructPtr->object = returnObjPtr; 


/* 


* Delete the temporary objects by reducing their RefCount 
* The object manager will free them, and associated 

* memory when the reference count becomes 0. 

*/ 


Tcl_DecrRefCount(indexObjPtr); 


/* 

* Don’t delete valueObjPtr - it’s the returnObjPtr 
* object. The task will core dump if you clear it, 
* and then use it. 

* Tcl_DecrRefCount(valueObjPtr) ; 

*/ 


return(returnStructPtr) ; 
} 


Note the following in regard to the previous example. 


—_ 


. This code implements the equivalent of set arrayName(Index) Value. 
. This section of code implements the equivalent of set arrayName(alpha) NewValue. The 


value assigned to returnObjPtr is a pointer to valueObjPtr, because there is no extra 
processing attached to the val ueObjPtr variable. 
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3. 


4. 


Note that you should use the Tc1_DecrRefCount function to free Tcl objects. Do not use the free 
function. 

The valueOQbjPtr is also created in this function. A pointer to this object will be returned by the 
Tcl_ObjSetVare call, but the reference count for this object is not incremented. 

Since this object is being returned as the returnObjPtr, the reference count should not 
be decremented. If a pointer to this object is passed to Tcl_DecrRefCount, the object will be 
destroyed, and returnObjPtr will point to a nonexistent object. When the Tcl interpreter tries to 
process the nonexistent object, it will not do anything pleasant. 


1c 
15 


COMPLEX DATA 


If you need to handle complex data (such as a structure) in your extension, there are some options. 


You can define the structure in your Tcl script as a list of values and pass that list to extension code 
to parse into a structure. 

You can use an associative array in the Tcl script, where each index into the associative array is a 
field in the structure. 

You can create a function that will accept the values for a structure in list or array format, parse 
them into a structure, place that structure in a hash table, and return a key to the Tcl script for 
future use. 


The following example shows how a Tcl associative array can be used to pass a structure into a C code 
extension. The code expects to be called with the name of an array that has the appropriate indices set. 
The indices of the array must have the same names as the fields of the structure. 
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Using an Associative Array to Define a Structure 


Tcl_Obj *indexPtr; 


Tcl_Obj *structElementPtr; 


struct demo { 
int firstInt; 
char x*secondString; 
double thirdFloat; 

} demoStruct; 


/* The names of the fields to be used as array indices */ 


char *fields[] = {"firstInt", "secondString", 
"thirdFloat", NULL }; 
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x Create an object that can be used with Tcl_ObjGetVar2 
* to find the object identified with the array and 

* jndex names 

*/ 


indexPtr = Tcl_NewStringObj(fields[0], -1); 


/* 

* Loop through the elements in the structure/ indices of 
* the array. 

*/ 


for (i=0; i<3; i++) { 
/* 
* Set the index object to reference the field 
* being processed. 


*/ 


Tcl_SetStringObj (indexPtr, fieldsLi], -1); 


* 


Get the object identified as arrayName( index) 
If that value is NULL, there is no 

* arrayName(index): complain. 

*/ 


+ 


structElementPtr = 
Tcl_ObjGetVar2(interp, objv£2], indexPtr, 0); 
if (structElementPtr == NULL) { 
Tcl_AppendResult(interp, 
"Array Index \"", fieldsLil, 
"\" is not defined ", (char *) NULL); 
returnStructPtr->status = TCL_ERROR; 


goto done; 
} 
/* 
* This is a strange way to determine which structure 
* element is being processed, but it works in the loop. 
* 
* If an illegal value is in the object, the error 
* return will be set automatically by the interpreter. 
*/ 
switch (i) { 
case 0: { 


int te 
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if (TCL_OK != 
Tcl_GetIntFrom0bj(interp, 
structElementPtr, &t)) { 
returnStructPtr->status = TCL_ERROR; 
goto done; 
} else { 
demoStruct.firstInt = t; 
} 
break; 
} 
case l: { 
char xt; 
if (NULL == (t = 
Tcl_GetStringFromObj(structElementPtr, NULL))) { 
returnStructPtr->status = TCL_ERROR; 
goto done; 
} else { 
demoStruct.secondString= 
(char *)malloc(strlen(t)+1); 
strcpy(demoStruct.secondString, t); 
} 
break; 
} 
case 2: { 
double t; 
if (TCL_OK != 
Tcl_GetDoubleFrom0bj(interp, 
structElementPtr, &t)) { 
returnStructPtr->;status = TCL_ERROR; 
goto done; 
} else { 
demoStruct.thirdFloat = t; 
} 
break; 
} 


printf("demoStruct assigned values: \n %d\n %s\n *f\n", 
demoStruct.firstInt, demoStruct.secondString, 
demoStruct.thirdFloat); 


The following example demonstrates populating a structure using the arraystr subcommand. 
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Example 11 
Script Example 

set struct(firstInt) "12" 

set struct(secondString) "Testing" 

set struct(thirdFloat) "34.56" 

demo arraystr struct 


Script Output 
demoStruct assigned values: 
12 
Testing 
34.560000 


The next example demonstrates a pair of functions that use a list to define the elements of a structure 
and save the structure in a hash table. These functions implement two new subcommands in the demo 
extension: demo liststr key listand key Jistanddemo getstr key. 

These functions introduce the Tcl list object. A Tcl list object is an object that contains a set of 
pointers to other objects. There are several commands in the Tcl library API to manipulate the list 
object. This example introduces only a few that are necessary for this application. 

Syntax: int Tcl_ListObjLength (interp, listPtr, lTengthPtr) 
Places the length of the list (the number of list elements, not not the string length) in 
the JengthPtr argument. function returns either TCL_OK or TCL_ERROR. 
Tcl_Interp *interp A pointer to the Tcl interpreter. 
Tcl_Obj */istPtr A pointer to the list object. 


int *lengthPtr A pointer to the integer that will receive the length of this 
list. 


Syntax: int Tcl_ListObjIndex (interp, listPtr, index, 
elementPtr) 
Places a pointer to the object identified by the index argument in the e/ementPtr 
variable. This function returns either TCL_OK or TCLERROR. 


Tcl_Interp *interp A pointer to the Tcl interpreter. 
Tcl_Obj *listPtr A pointer to the list object. 
int index The index of the list element to return. 


Tcl.Obj **xelementPtr The address of a pointer to a Tc1_0bj that will be set 
to point to the Tc1_0bj that is referenced by index. 


Syntax: Tcl_0bj* Tcl_NewListObj (count, objv) 
Returns a pointer to a new Tc1_Obj that is a list object object pointing to each of the 
objects in the objv array of objects. 
int count The number of objects defined in the ob jv array of objects. 
Tcl_0bj *objvf[]  Anarray of pointers to Tcl objects that will be included 
in this list. 
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List to Structure Example 


* CmdReturn xDemo_ListstrCmd (ClientData info-- 

Accepts a key and a list of data items that will be used to 
fill a pre-defined structure. 

The newly filled structure pointer is saved in a hash 
table, referenced by ‘key_Value’. 


Arguments: 
objvL0] "demo" 
objvf1] “liststr" 
objv£2] key_Value 
objv£[3] structure_List 


Results: 
Places a structure pointer in the hash table. 


Side Effects: 


CmdReturn *Demo_ListstrCmd (ClientData info, 
Tcl_Interp xinterp, 
int objc, 
Tcl_Obj *xobjv[]) { 
Tcl_HashEntry *xhashEntryPtr; 
CmdReturn *returnStructPtr; 
char *returnCharPtr; 
Tcl_Obj *returnObjPtr; 
Tcl_Obj *listElementPtr; 
int listlen; 
in 
n 


t isNew; 

t length; 
char *tmpString; 
int i; 


char *hashEntryContentsPtr; 
char *hashKeyPtr; 
struct demo { 
int firstInt; 
char *secondString; 
double thirdFloat; 
} *xdemoStruct; 
debugprt("Demo_ListstrCmd called with 4d args\n", objc); 


/* 
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x Allocate the space and initialize the return structure. 
*/ 
returnStructPtr = (CmdReturn *) malloc(sizeof (CmdReturn) ); 


returnStructPtr->status = TCL_OK; 


returnStructPtr->object = NULL; 
returnCharPtr = NULL; 

returnObjPtr = NULL; 

/* 

x Allocate space for the structure 
*/ 


demoStruct = (struct demo *) malloc(sizeof (struct demo) ); 


/* 
x Get the length of the list, then step through it. 
*/ 

Tcl_ListObjLength(interp, objv£[3], &listlen); 


for(i=0; i< listlen; i++) { 
/* 
* Extract a list element from the list pointer 
*/ 
Tcl_ListObjIndex(interp, objv[3], i, &listElementPtr); 


debugprt("Position: %d : Value: %s\n", 
i, Tcl_GetStringFromObj(listElementPtr, NULL)); 


* A strange way to determine which structure element 
is being processed, but it works in the loop. 

If an illegal value is in the object, the error 

* return will be set automatically by the interpreter. 
«/ 


+ 


+ 


switch (i) { 
case 0: { 
int t; 
if (TCL_OK != 
Tcl_GetIntFrom0bj(interp, 
listElementPtr, &t)) { 
returnStructPtr->status = TCL_ERROR; 
goto done; 
} else { 
demoStruct->firstInt = t; 
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break; 
} 


case 1: { 
char xt; 
if (NULL == (t = 
Tcl_GetStringFrom0bj(listElementPtr, 
NULL))) { 
returnStructPtr->status = TCL_ERROR; 
goto done; 
} else { 
demoStruct->secondString= 
(char *)malloc(strlen(t)+1); 
strcpy(demoStruct->secondString, t); 
} 
break; 
} 


case 2: { 
double t; 
if (TCL_OK != 
Tcl_GetDoubleFrom0bj(interp, 
listElementPtr, &t)) { 
returnStructPtr->status = TCL_ERROR; 
goto done; 
} else { 
demoStruct->thirdFloat = t; 
} 
break; 
} 


* Extract the string representation of the object 
* argument, and use that as a key into the hash table. 


* 


If this entry already exists, complain. 
*/ 
hashKeyPtr = Tcl_GetStringFrom0bj(objv£2], NULL); 
hashEntryPtr = Tcl_CreateHashEntry(demo_hashtb1Ptr, 
hashKeyPtr, &isNew); 
if (lisNew) 
char errString[80]; 
sprintfCerrString, 
"Hashed object named \"%s\" already exists.\n", 
hashKeyPtr); 


15.4 Complex Data 


/x* 
* Both of these strings will be added to the Tcl 
* script global variable errorInfo 
*/ 


Tcl_AddObjErrorInfo(interp, errString, 
strlen(errString)); 
Tcl_AddErrorInfo(interp, “error in Demo_CreateCmd") ; 


/* 
* This SetErrorCode command will set the Tcl script 
* variable errorCode to "APPLICATION {Name exists}" 
*/ 


Tcl_SetErrorCode(interp, "APPLICATION", "Name exists", 
(char *) NULL); 


/* 
* This defines the return string for this subcommand 
*/ 


Tcl_AppendResult(interp, "Hashed object named \"", 
hashKeyPtr, "\" already exists.", (char *) NULL); 


returnStructPtr->status = TCL_ERROR; 
goto done; 


* 


If we are here, then the key is unused. 
Get the string representation from the object, 
and make a copy that can be placed into the hash table. 


+ 


+ 


tmpString = Tcl_GetStringFrom0bj(objv[3], &length); 


hashEntryContentsPtr = (char *) malloc(length+1); 
strcpy(hashEntryContentsPtr, tmpString) ; 
debugprt("setting: %s\n", hashEntryContentsPtr) ; 
Tcl_SetHashValue(hashEntryPtr, demoStruct); 


done: 
if ((returnObjPtr == NULL) && (returnCharPtr != NULL)) { 
returnObjPtr = Tcl_NewStringObj(returnCharPtr, -1); 
} 
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returnStructPtr->object = returnObjPtr; 
if (returnCharPtr != NULL) {free(CreturnCharPtr) ; } 
return returnStructPtr; 


CmdReturn xDemo_GetstrCmd ()-- 
Demonstrates retrieving a structure pointer from a hash 
table, and stuffing that into a list. 


/ 

* 

* 

* 

* 

* Arguments 

* objvl0]: "demo" 

* objvllj: "“getstr" 
* objvi2]: hash_Key 
* 

* 

* 

* 

* 

* 


Results 
No changes to hash table. Returns saved value, or sets error. 


Side Effects: 


CmdReturn *Demo_GetstrCmd (ClientData info, 
Tcl_Interp xinterp, 
int objc, 
Tcl_Obj xobjvlJ) { 
Tcl_HashEntry *xhashEntryPtr; 
CmdReturn *returnStructPtr; 
char *returnCharPtr; 
Tcl_Obj *returnObjPtr; 
Tcl_Obj «listPtrPtr[3]; 
char *hashKkeyPtr; 
struct demo { 
int firstInt; 
char *secondString; 
double thirdFloat; 


} xdemoStruct; 

debugprt("Demo_GetCmd called with 4d args\n", objc); 

/* 

x Allocate the space and initialize the return structure. 
*/ 


returnStructPtr = (CmdReturn *) malloc(sizeof (CmdReturn) ); 


returnStructPtr->status = TCL_OK; 
returnStructPtr->object NULL; 
returnCharPtr = NULL; 
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returnObjPtr = NULL; 


+ 


Get the key from the argument 

x And attempt to extract that entry from the hashtable. 
If the returned entry pointer is NULL, this key is not 
in the table. 


+ 


* 


*/ 


hashkKeyPtr = Tcl_GetStringFrom0bj(objv£2], NULL); 
hashEntryPtr = Tcl_FindHashEntry(demo_hashtb1Ptr, 
hashKeyPtr); 


if (hashEntryPtr == (Tcl_HashEntry *) NULL) { 
char errString[80]; 
Tcl_Obj *errCodePtr; 


/* 

* This string will be returned as the result of the 
* command. 

*/ 


Tcl_AppendResult(interp, 
"can not find hashed object named \"", 
hashkeyPtr, "\"", (char *) NULL) 
returnStructPtr->status = TCL_ERROR; 
goto done; 
} 
/* 
* If we got here, then the search was successful and we 
* Can extract the data value from the hash entry and 
* return it. 
*/ 


demoStruct = (struct demo *)Tcl_GetHashValue(hashEntryPtr) ; 


/* 


+ 


+ 


and then merge them into a list object. 


* Return the list object. 
*/ 
listPtrPtrLO] = Tcl_NewIntObj(demoStruct->firstInt); 
listPtrPtr[1] = 
Tcl_NewStringObj(demoStruct->secondString, -1); 
listPtrPtr[2] = 
Tcl_NewDoubleObj( (double) demoStruct->thirdFloat); 


Create three objects with the values from the structure, 
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returnObjPtr = Tcl_NewListObj(3, listPtrPtr); 
debugprt("returnString: %s\n", returnCharPtr) ; 


done: 
if ((returnObjPtr == NULL) && (returnCharPtr != NULL)) { 
returnObjPtr = Tcl_NewStringObj(returnCharPtr, -1); 
} 
returnStructPtr->object = returnObjPtr; 
if (returnCharPtr != NULL) {free(CreturnCharPtr) ; } 
return returnStructPtr; 


The following script example demonstrates using the 1iststr and getstr subcommands. 
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Script Example 
fdemo liststr keyl [list 12 "this is a test" 34.56] 
% demo getstr keyl 


Script Output 
12 {this is a test} 34.56 


EMBEDDING THE TCL INTERPRETER 


The most common use of Tcl is as an interpreter with extensions to add functionality. The most com- 
mon commercial use of the Tcl interpreter is to embed it within a C, C# or C++ application. In this 
architecture, the mainline code is compiled and the Tcl interpreter is invoked to run specific scripts—to 
read a configuration file, display a GUI, to allow a user to customize behavior, etc. 

This technique is very powerful, since it provides you with the speed and power of a compiled 
language with the versatility and ease of customization of an interpreted language. 

Examples of this style of programming include most of the high-end CAD and EDA packages, 
Cisco’s IOS, the TuxRacer game, the sendmail tclmilter and the Apache Rivet package. These appli- 
cations define configuration options and simple operations in a Tcl script file and then perform the 
CPU-intensive operations within a compiled section. 

Embedding the Tcl interpreter within a C application requires a few items: 


1. The Tcl include files (tcl.h, tk.h). 
2. The Tcl library for the target system (libTcl.a, libTcl.so, libTcl.d11.) 
3. Some support code in the application to link to the Tel interpreter. 


The include files and libraries are included with the standard Tcl distributions, or they will be 
created if you compile Tcl and Tk from source (described in the next section). 
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Embedding Tcl or Tk into a C or C++ application uses these functions: 


Tcl_FindExecutable Fills internal Tcl variable that is used by info nameofexecutable. 
This is not absolutely required, but is good to include. 


Tcl_CreateInterp Creates a new interpreter. After this command has been completed the 
new interpreter can be used for some applications. The compiled com- 
mands will be available, but Tcl commands that are implemented in 
scripts (for example, parray) will not be loaded until Tcl_Init has 
been called. 


Tcl_Init Loads the Tcl initialization scripts to fully initialize the interpreter and 
create all standard commands. 

Tk_Init Loads the Tk initialization scripts. This is only valid if you have linked 
the Tk interpreter into your application. 

Tcl_Eval Evaluates a Tcl script and returns TCL_OK or TCL_FATIL. 

Tcl_Exit Clean up and exit. 


The Tcl_FindExecutable and Tcl_CreateInterp function calls can be done in any order. Both 
of these should be done before calling the Tcl_Init or Tk_Init functions. The Tcl_Init function 
should be invoked before Tk_Init. The Tcl_Eval function should not be called until the previous 
functions have returned. 

The first two function calls when initializing an embedded Tcl interpreter should be 
Tcl_FindExecutable and Tcl_CreateInterp. These two calls can be done in either order, but 
both should be done before calling Tcl_Init. 


Syntax: void Tcl_FindExecutable (argv0) 
Determines the complete path to the executable. If the argv0 argument includes a 
rooted path that is used, else the current working directory and argv[0] value 
are used. 
argvO Cand C++ applications pass the command line arguments as an array of 
strings. The first element of this array will be the name of the executable. 


Syntax: Tcl_Interp «Tcl_CreateInterp () 
Creates a new interpreter and defines the basic commands. 


The Tcl_CreateInterp command returns a pointer to the new Tcl interpreter. This is actually a 
pointer to the Tcl interpreter state structure. Multiple interpreters share the same code base, but each 
have their own state structure. 

This interpreter pointer is passed to most Tcl library functions. 

The Tcl_Init and Tk_Init functions both require the tt Tcl_Interp pointer. 


Syntax: int Tcl_Init (interp) 
Initializes the Tcl Interpreter. This involves loading and evaluating the 
init.tcl script and other scripts in the library. 
interp A pointer to the Tcl_Interp structure returned by a call to 
Tcl_CreateInterp. 
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The Tcl_Init and Tk_Init functions return an integer return that conforms to normal C 
conventions—a “0” (TCL_OK) indicates success and a non-zero return (TCL_FAIL) indicates an error. 
Information about the failure can be obtained by using Tcl_GetVar to retrieve the contents of the 
errorInfo global variable. 

After an interpreter has been created and initialized your application can send scripts to be evalu- 
ated. These scripts can be simple Tcl commands, or long and complex scripts. There are several flavors 
of the Tc1_Eval command depending on whether the script is already in a Tcl object, a file, or included 
in the code as a string. The most basic function is Tc]_Eval. 


Syntax: Tcl_Eval (interp, string) 
Evaluate a string of Tcl commands within an interpreter. 
interp A pointer to the Tcl_Interp structure returned by a call to 
Tcl_CreateInterp. 


string A printable string consisting of one or more Tcl commands. 


The last step is to invoke Tc1_Exit to exit your application. This is preferred over the normal exit 
function because it will do a bit more cleanup of the Tcl interpreter and make sure no data is left in 
limbo. 


Syntax: Tcl_Exit (status) 
Clean up the Tcl interpreter state and exit. 


status An integer status to return to the OS. The standard is to return 0 for a 
success and non-zero for some exception exit. 


The next example is a minimal main.c which will create and initialize a Tcl interpreter and then 
load and evaluate the commands in a file. 
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main.c 

#include <stdlib.h> 

#Finclude <tcl.h> 

dFinclude <tk.h> 


main(int argc, char xargvLl]) { 


// Tcl ‘glue’ variables 
Tcl_Interp *interp; /* Interpreter for application. x/ 
int rtn; 


// Create the interp and initialize it. 
Tcl_FindExecutable(argv[0]); 
interp = Tcl_CreateInterp(); 


if (Tcl_Init(interp) == TCL_ERROR) { 
return TCL_ERROR; 
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if (Tk_Init(interp) == TCL_ERROR) { 
return TCL_ERROR; 
} 


// Run the Tcl script file - hardcoded for myScript.tcl 
rtn = Tcl_Eval(interp, "source myScript.tcl"); 
if (rtn != TCL_OK) { 

printf("Failed Tcl_Eval: %d \n&%s\n", rtn, 


Tcl_GetVar(interp, "errorInfo", TCL_GLOBAL_ONLY)); 
exit(-1); 


Tcl_Exit(0); 


In the previous example, the script performs all the operations. It might load another extension, 
create a GUI, create a web server or anything else. 

If you’re embedding Tcl within a set of compiled code, you probably have a set of compiled func- 
tions that you’d like the Tcl scripts to have access to. These can be built into the executable, rather than 
loaded from a compiled library, as is done with extensions. 

The functions described in the previous sections about building a Tcl extension are also used to 
create new commands to be used with an embedded interpreter. 

The next example shows a main.c with a new command being created. The new command is 
factorcount, which finds the number of factors a value has by dividing the value by all smaller 
integers to see which will divide it evenly. This function has no use except that it chews up fewer CPU 
cycles when compiled than it does when interpreted. 
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main.c with new command 


dFinclude <stdlib.h> 
dFinclude <math.h> 
dFinclude <tcl.h> 
dFinclude <tk.h> 


dFinclude "./factorcountInt.h" 


main(int argc, char xargvL]) { 


// Tcl ‘glue’ variables 
Tcl_Interp *interp; /* Interpreter for application. x/ 
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int rtn; 


// Create the interp and initialize it. 
interp = Tcl_CreateInterp(); 
Tcl_FindExecutable(argv[0]); 


if (Tcl_Init(interp) == TCL_ERROR) { 
return TCL_ERROR; 
} 


if (Tk_Init(interp) == TCL_ERROR) { 
return TCL_ERROR; 


// Add the factorcount command 
Tcl_CreateObjCommand(interp, "factorcount", 
Factorcount_Cmd, (ClientData) NULL, NULL); 


// Run the Tcl script file - hardcoded for myScript.tcl 
rtn = Tcl_Eval(interp, "source myScriptFactor.tcl"); 


if (rtn != TCL_OK) { 
printf("Failed Tcl_Eval: %d \n’s\n", rtn, 
Tcl_GetVar(interp, "“errorInfo", TCL_GLOBAL_ONLY)); 
exit(-1); 


The Factorcount_Cmd function is mostly code to check that the Tcl command was called cor- 
rectly. In a real application there would probably be more logic than checking that the script writer 
used the right parameters. 
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factor.c 

#finclude "./factorcountInt.h" 


int Factorcount_Cmd(ClientData factorcount, 
Tcl_Interp xinterp, 
int objc, 
Tcl_Obj * CONST xobjv) { 


/* ClientData factorcount; /* Not used. */ 
/*x Tcl_Interp *interp; /* Current interpreter. x*/ 
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/x int objc; /x Number of arguments. */ 
/* Tcl_Obj *CONST objvld; /* Argument objects. */ 


// Tcl variables 


nt result; 
Tcl_Obj *returnValue; 
// function variables 
int product; // Product to find factors for - from user 
int count; // Count of factors 
int 7; // loop variable 
nt. £25 // Temporary factor variable 


// Assume everything will be ok 
result = TCL_OK; 


/* 
* Initialize the return value 


*/ 


returnValue = NULL; 


/* 
* Check that we have a command and number 
*/ 
if (objec < 2) { 
Tcl_WrongNumArgs(interp, 1, objv, 
"factorCount number"); 
return TCL_ERROR; 
} 
if (TCL_OK != 
Tcl_GetIntFrom0bj(interp, objv£1l], &product)) { 
result = TCL_ERROR; 
goto done; 
} 
count = 0; 


for (i=l; 1 < product; i++) { 
f2 = product/i; 
if (f2*i == product) { 
countt++; 
} 


returnValue = Tcl_NewIntObj(count); 
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done: 


/* 
* Set the return value and return the status 
*/ 


if (returnValue != NULL) { 
Tcl_SetObjResult(interp, returnValue); 


return result; 


The factorcountInt.h file is mostly the previously described boilerplate with these lines to 
define the new command: 


factorcountInt.h 
[xxx 
extern "C" { 
x**/ 


EXTERN EXPORT(int,Factorcount_Cmd) _ANSI_ARGS 
((ClientData, Tcl\_Interp *, int, Tcl\_Obj * CONST x)); 


[xxx 


} 


x**/ 


The example script to go with this script will create a small GUI and invoke the factorcount 
command to evaluate the user input. 
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Script Example 


set done 0 


label .11 -text "Enter Number:" 
entry .el -textvar product 


button .bl -text "go" -command {set answer [factorcount $product]} 
button .b2 -text "done" -command {set done 1} 


label .12 -text "Factors:" 
label .13 -textvar answer 
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grid .11 .el 
grid .bl .b2 
grid .12. 413 


vwait done 


Script Output 


nter Number:|98765432]| 


go done | 


Factors: iL 


The script uses vwait to force the script to run until the user exits. An application that intends to 
be GUI driven might follow Tcl_-Eval with a call to Tcl_MainLoop to enter the event loop and stay 
there until the interpreter exits. 


Syntax: Tk_MainLoop () 
Calls the event loop processing code repeatedly. Returns 
when the last window is destroyed. 


6 BUILDING TCL AND TK FROM SOURCES 


If your application requires more than just simple interfaces to the Tcl and Tk libraries, odds are good 
that you'll want to look at the source or build your libraries from the source and include debugging 
information. Tcl and Tk are relatively easy to build from source. The source distribution includes sup- 
port for building Tcl/Tk under Linux, Unix, Mac OS/X and Windows. The build files include support 
for GCC compiler as well as MS Visual C, Borland C and XCode. 

The first step in building your own Tcl and Tk libraries and interpreters is to acquire the sources. 
The Tcl source tree is maintained core.tcl.tk, with mirrors at www. sourceforge.net. 

The best way to get the most current bleeding edge or most recently maintained source code is to 
use the fossil repositories at http://core.tcl.tk. 

The baseline Tcl and Tk sources are maintained using the fossil distributed code management 
application written by D. Richard Hipp. The executable (or source) for this can be obtained from 
http://www. fossil-scm.org. 

Once you have fossi1 installed on your system you can install the Tcl and Tk sources by opening 
a command or xterm window and typing commands similar to these. 


OOOO —_—n—  ay»-»z=_ 
Example 18 


Script Example 


fossil clone http://core.tcl.tk/tcl tcl.fos 
fossil clone http://core.tcl.tk/tk tk.fos 
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mkdir tcl 

cd tcl 

fossil open ../tcl.fos 
Cds 

mkdir tk 

fossil open ../tk.fos 


Once the sources are unpacked, the tcl and tk folders will include folders named macosx, unix 


and win. Within each of these folders is a README file with information about how to build Tcl or Tk 
for that platform. This information changes occasionally as platforms evolve, so it’s best to check the 
README before trying to build Tcl or Tk. 


Depending on the tools you have installed in your development environment (minimally, a C 


compiler, a make utility and a library utility), the steps to compile will resemble the following: 


Windows 

The source code distribution includes a Developer Studio workspace and project file. 

Most commonly, Tcl is compiled from the command line using the nmake application that is 
provided with Visual C++ 6.0. 

If you use nmake the command to compile Tcl is: 

cd sourceFolder/win 

nmake -f makefile.vc 


Linux/Unix 

The Tcl and Tk distributions include a configure script to determine the exact configuration 
of your system and allow you to fine-tune the options. 

The steps to compile Tcl and Tk are: 

cd sourceFolder/unix 

./configure 

make 


Mac OSX 

If you have installed the GNU make and GCC, Tcl and Tk can be built using the provided 
makefile. 

cd sourceFolder/macosx 

make 


Once a new interpreter has been created, you can install it with the command make instal]. 


| 


15.7 BOTTOM LINE 


A Tcl extension can be built for several purposes, including the following. 
a. Adding graphics to an existing library 
b. Adding new features to a Tcl interpreter 
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c. Creating a rapid prototyping interpreter from a library 
d. Creating a script-driven test package for a library 
A Tcl extension must include the following. 
a. An ExtName_Init function 
b. Calls to Tcl_CreateCommand to create new Tcl commands 
c. Code to implement each new Tcl command 
A Tcl extension should also include the following. 
a. An include file named extNameInt.h 
b. A makefile or IDE project files 
c. Separate directories for generic code, platform-specific files, documentation, and tests 
A Tcl extension may include other files as necessary to make it a maintainable, modular set 
of code. 
New Tcl commands are defined with the Tcl_CreateObjCommand or Tcl_CreateCommand 
command. 
Syntax: int Tcl_CreateObjCommand (interp, cmdName, func, clientData, 
deleteFunc) 


Syntax: int Tcl_CreateCommand (interp, cmdName, func, clientData, 
deleteFunc) 

The C function associated with the new Tcl command created by Tcl_Create...Command should 

have a function prototype that resembles the following. 


int funcName (clientData, interp, objc, objv) 


You can get a native or a string representation from a Tcl object with the Tcl_GetIntFrom0bj, 
Tcl_GetDoubleFrom0bj, or Tcl_GetStringFrom0bj command. 

Syntax: int Tcl_GetIntFrom0bj (interp, objPtr, intPtr) 

Syntax: int Tcl_GetDoubleFrom0bj (interp, objPtr, doublePtr) 

Syntax: char *Tcl_GetStringFrom0bj(objPtr, lengthPtr) 

You can create a new object with one of the following functions. 

Syntax: Tcl]_O0bj *Tcl_NewIntObj(intValue) 

Syntax: Tcl_0bj *Tcl_NewDouble0bj(doubleValue) 

Syntax: Tcl_0bj «Tcl_NewStringObj (bytes, length) 

You can modify the content of an object with one of the following functions. 

Syntax: void Tcl_SetIntObj (objPtr, intValue) 

Syntax: voi -SetDoubleObj (objPtr, doubleValue) 

Syntax: voi -SetStringObj (objPtr, bytes, length) 

Syntax: voi -AppendToObj (objPtr, bytes, length) 

Syntax: voi -AppendObjloObj (objPtr, appendObjPtr) 

Syntax: void Tcl_AppendStringsToObj (objPtr, string, ..., NULL) 

The results of a function are returned to the calling script with the functions Tc]l_SetObjResult 
and Tcl_SetResult. 
Syntax: void Tcl_SetObjResult (interp, objPtr) 
Syntax: void Tcl_SetResult (interp, string, freeProc) 


f] f] f H 
1 1 1 1 
Os IY 2 Or HO) 


Sh eh Oo eo 


636 CHAPTER 15 Extending Tcl 


e The status of a function is returned to the calling script with the functions Tc]_AddObjErrorInfo, 
Tcl_AddErrorInfo, Tcl_SetObjErrorCode, and Tcl_SetErrorCode, which set the error - 
Code and error Info global Tcl variables. 

Syntax: void Tcl_AddObjErrorinfo (interp, message, length) 
Syntax: void Tcl_AddErrorInfo (interp, message) 

Syntax: void Tcl_SetObjErrorCode (interp, objPtr) 

Syntax: void Tcl_SetErrorCode (interp, elementl, element2...NULL) 

e Tcl provides an interface to fast hash table database functions to allow tasks to save and retrieve 
arbitrary data based on keys. A hash table must be initialized with the Tcl_InitHashTable 
function. 

Syntax: void Tcl_InitHashTable (tablePtr, keyType) 

e Hash table entries may be manipulated with the following functions. 

Syntax: Tcl_HashEntry «Tcl_CreateHashEntry (tablePtr, key, newPtr) 
Syntax: Tcl_HashEntry *Tcl_FindHashEntry (tablePtr, key) 
Syntax: void Tcl_DeleteHashEntry (entryPtr) 

e¢ Data may be retrieved or deposited in a Tc] _HashEntry with the following functions. 

Syntax: ClientData TclGetHashValue (entryPtr) 
Syntax: void TclSetHashValue (entryPtr, value) 

e A match to a string can be found in an array of strings with the Tcl_GetIndexFrom0bj 
function. 
Syntax: int Tcl_GetIndexFrom0bj (interp, objPtr, tb]Ptr, msg, flags, 

indexPtr) 

e The content of Tcl variables can be accessed with the following functions. 

Syntax: Tcl_0bj «Tcl_ObjGetVar2 (interp, idlPtr, id2Ptr, flags) 
Syntax: char *Tcl_GetVar2 (interp, name2, namel, flags) 

e The content of Tcl script variables can be set with the following functions. 

Syntax: Tcl_0bj *Tcl_ObjSetVar2 (interp, idlPtr, id2Ptr, newValPtr, flags) 
Syntax: char *Tcl_SetVar2 (interp, namel, name2, newstring, flags) 

e A Tcl list is implemented with a Tcl object that contains an array of pointers to the elements of the 
list. You can create a Tcl list within a C function with the Tc]_NewListObj function. 
Syntax: Tcl]_Obj* Tcl_NewListObj (count, objv) 

e You can get the length of a list with the Tc]_List0ObjLength function. 

Syntax: int Tcl_ListObjLength (interp, listPtr, lengthPtr) 

e You can retrieve the list element from a particular index in a list with the Tcl_ListObj Index 
function. 


Syntax: int Tcl-ListObjIndex (interp, listPtr, index, elementPtr) 


Syntax: A Tcl or Tk interpreter can be embedded within a C application using the 
Tcl_FindExecutable, Tcl_CreateInterp, Tcl_Init, Tk_Init and Tcl_Eval 
functions. 

Syntax: Tcl and Tk can be built from source on Unix, Linux, Mac OSX and Windows systems. 


Syntax: The Tcl source code is available from http: //core.tcl.tk and http://www 
.sourceforge.net 
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15.8 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the 
chapter. They can be answered in a few words or a 1-5 line script. 

These problems should each take under a minute to answer. 

200-299 These quick exercises require some thought or information beyond 
that covered in the chapter. They may require reading a man page or 
making a web search. A short script of 1-50 lines should fulfill the 
exercises, which may take 10-20 minutes each to complete. 

800-399 Long exercises may require reading other material, or writing a few 
hundred lines of code. These exercises may take several hours to 
complete. 


e 100 If you have a standalone application with no source code, or library documentation, is this a 
likely candidate for a Tcl extension? Why or why not? 

e 101 What Tcl library call adds a new command to a Tcl interpreter? 

e 102 What Tcl command will return the integer value of the data in a Tcl object? What will be 
returned if the object does not contain integer data? 

e 103 What data format is always valid for Tcl data? 

e 104 Can the Tcl_SetVar function be used to assign a value to a variable that does not exist ? 

e 105 Can you assign a string of binary (not ASCII) data to a Tcl object? 

e 106 What value should a successful command return? 

e 107 What command will add a string to the errorInfo global variable? 

e 108 Given an extension named checksum, what should the initialization function be named? 

e 109 What would be the path and name of the include file for internal use by the extension foo? 
(Following the TEA path and name conventions.) 

e 110 Which library command will append a string onto the data in a Tcl object? 

e 111 Which library command will create a new Tcl object with an integer value? 

e 112 Which library command will append a new list element to a Tcl list variable? 

e 113 Cana Tcl interpreter be embedded in a compiled application?. 


e 200 If you have an application built from an internally developed function library, describe how 
you could use a Tcl extension to perform automated integration and unit testing for the package. 

e 201 Find the sample extension code on the companion website and compile that on your preferred 
platform. 

e 202 Write a Tcl extension that will calculate and return a simple checksum (the sum of all bytes) of 
the content of a Tcl variable. 

e 203 Write a Tcl extension that will return a string formatted with the sprintf command. This new 
command will resemble the Tcl format command. 
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e 204 Extend the embedded Tcl example in Section 15.5 with a new command to return the area of a 
circle of a given radius. The area of acircle is 3.14 * radius * radius. 

e 205 Modify the embedded Tcl example in Section 15.5 to have an internal string with a script to 
evaluate instead of sourcing an external Tcl file. 

e 300 Write a Tcl extension that will save data in a structure, as shown in Example 10. Add a 
subcommand to retrieve the values from the structure and populate a given array. 

e 301 Port the extension written for problem 202 to at least one other platform: MS Windows, UNIX, 
or Macintosh. 

e 302 Write a set of test scripts for the extension written in problem 203 to exercise the sprintf 
function and prove that it behaves as documented. 

e 303 Port the extension and tests written in problems 203 and 302 to another platform. Confirm that 
sprintf behaves the same on both platforms. 


CHAPTER 


Applications with Multiple 
Environments 


Many applications need to control more than one application environment. For example: 


A TCP/IP server needs to support multiple clients. 

A test platform may be testing several sets of hardware at once. 

Games may be tracking multiple users. 

Tcl script may be controlling several processor blades in a multi-processor environment. 


Tcl provides several ways to manage the multiple environments. These techniques range from pure 


Tcl solutions to compiled code. 


Here are the commonly used techniques. Each will be discussed in more detail later in this chapter. 


Event loop 

You can write many multiple environment applications using the Tcl event queue to evaluate 
procedures when they are required and the upvar command to map a persistent state variable into a 
procedure’s local scope. This technique is used by the tcl httpd application and the http package 
to support multiple concurrent connections. 

This style works best when all of your threads use the same set of procedures, but require 
separate sets of state data. 
Slave interpreters 

If your application requires private procedures or modifies procedures during execution, you 
can create a new interpreters for each execution thread. Each new thread has it’s own procedures, 
packages and global variables. An interpreter can be created either as a full-function interpreter, or 
a safe interpreter that cannot touch a filesystem or interact with the outside world. 

Interpreters are created as a hierarchy, with a single parent having multiple child interpreters, 
each of which may have more child interpreters. 

Using slave interps is suitable for Agent style applications, machine control and testing 
applications and for network application that interact with potentially malicious clients. 
Thread package 

The default Tcl interpreter is thread safe, but does not include thread support. The thread exten- 
sion can be downloaded from sourceforge or (if you are using an ActiveTcl distribution) installed 
using teacup. 

The thread package allows a Tcl application to start multiple operating system threads. These 
threads can communicate and coordinate with each other using mutexes and messages. 

Each thread is a peer, there is no hierarchy among threads. 

This technique works well if you need the operating system to establish the threads and perhaps 
take advantage of multiple processors. 
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e C library thread support 

The Tcl library includes several commands for creating new threads and interpreters and 
controlling the interactions between the threads. 

If you are working with an application that creates threads for each connection (i.e., send- 
mail creates a new thread for each mail message) then you will need to use the Tcl library thread 
functions to initialize the threads. 

This technique is necessary when interfacing with existing object code libraries that use 
threading. 


16.1 EVENT LOOP 


The Tcl interpreter includes an event loop to distribute events to procedures that can process them. 
These events can include data becoming available on a socket, a timer expiring, a variable being 
modified, mouse events and more. 

In order to use the event loop your code must: 


—_ 


. Register scripts to be processed when an event occurs. 
2. Wait for events. 


You can register a script to be processed using one of these commands: 


e fileevent 
To register a script to be evaluated when data is available to be read from a file or socket. 


e trace 

To register a script to be evaluated when a variable or procedure is accessed. 
e after 

To register a script to be evaluated when a timer event occurs. 
e bind 


To register a script to be evaluated when a Windows event (button press, mouse move, etc.) occurs. 


How you cause your application to wait for events depends on whether your application is run using 
wishortclsh. 

If you are using wish to evaluate your program, you don’t need to do anything to cause your 
application to wait for events. A wi sh application automatically waits for events after it has processed 
all the commands in a script file. 

The tclsh interpreter defaults to evaluating all the commands in a script and then exiting. The 
vwait command (discussed in Chapter 4) will cause a Tcl script to pause and wait until a variable 
changes value. This command is commonly used to create modal user interfaces and to force a network 
server to run until something explicitly causes it to exit. 


16.1.1 Using fileevent 


The fi leevent command registers a script to be evaluated whenever a channel requires service. The 
most common use of this is to register a script to be evaluated when a channel has data to be processed. 
This allows an application to perform a read or gets command only when data is available instead of 
performing a blocking read or requiring a round-robin loop. 
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If your application is controlling a slow device, like a modem, the fi1eevent command can be 
used to evaluate a script when the device buffer is ready to accept fresh data. 

A single application can register scripts to handle file events associated with multiple channels. 
This technique is used in TCP/IP daemons (like a web or chat server) to support multiple simultaenous 
connections. 

The socket and gets commands are introduced in Chapter 4. 


Syntax: fileevent channel direction ?script? 
Register a script to be evaluated when a channel can be serviced. 
channel The channel to be read from or written to. 
direction The direction of data flow. Acceptable values are readable 
or writeable 
?script? Anoptional script to be evaluated when the channel can be 


processed. If this argument is not provided, the previously 
registered script is returned. 


This example shows a procedure that reads a line of data from a socket and then prints it to stdout. 
When the line of data is the word exit, the variable done is modified and the vwai t command stops 
waiting, allowing the task to exit. 


——— eee 
Example 1 


Using Fileevent 


## proc readData {channel} — 
i Read data from a channel and print it to stdout 
df Arguments 


if channel: An open socket or other channel that \ 
if has data available for reading. 

# 

tf 


proc readData {channel} { 
global done 
set len [gets $channel line] 
if {$len < 0} { 
puts "FAIL " 
} 
if {$line eq "exit"} { 
set done 1 
} 
puts “Just read $len bytes in $line" 
} 


## Open a socket connection to port 53210. 
## Port 53210 is attached to a TCP/IP server that generates data 
set channel [socket 127.0.0.1 53210] 


i## Register a procedure to be evaluated when there is data 
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if to be read 
fileevent $channel readable "“readData $channel" 


set done 0 
vwait done 
= 

If your application is processing multiple connections, it probably has state information associated 
with each connection that it needs to keep track of. 

The upvar command is a useful way to link state data to a set of procedures. The upvar command 
links a variable in a higher-level scope to a variable in the local scope. This technique is used in the 
http package. 

The upvar command is discussed in detail in Chapter 7. 


Syntax: upvar ?level? variableName newName 
?level? Optional level in which the variable exists. 
Formats for 7eve/ are: 


-number Number represents the number of calling 
scopes to count up. - 1 is the scope that the 
current procedure was called from. 
#number Number represents the number of calling 
scopes to count down from the global 
scope. The global scope is #0. 
By default, the value of 1 evel is - 1: the scope of the process 
that called the current procedure. 


variableName A variable that already exists. 
newName A local variable. 


The following example shows a simple TCP/IP server that reads lines of data and changes the status 
and data indices of a state variable. The state variables exist in the global scope, and each has a unique 
name which is mapped to the local scope variable State. 

When the server accepts a socket connection a new channel is created and the acceptClient 
procedure is evaluated with the name of the new channel. This procedure initializes the state variable 
and registers the readData procedure and the name of the channel as an argument as a script to be 
invoked when data is available for reading. 

Each time data becomes available to be read, the readData procedure is evaluated. This procedure 
uses the name of the channel to map the global state variable into the local variable named State, and 
then reads and processes the available data. 


$$ 
Example 2 
Using Fileevent with Multiple Clients 

## proc acceptClient {channel ip port}—— 

ld Accept a connection from a remote client 

if Arguments 

if channel The channel assigned to this connection 
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it = ip The IP address of the client 
# sport The port assigned to this connection 
## Results 


i## A new channel is opened and and fileevent assigned 
i 
proc acceptClient {channel ip port} { 

upvar #0 State_$channel State 

set State(ip) $ip 

set State(status) "Waiting" 

fileevent $channel readable "“readData $channel" 


dt proc readData {channel} 


i## Read data when it is available and change status as required. 


df Initially starts with status== "Waiting". 

if When data is read, status changes to "Reading" 

## When the word ‘DONE’ is read, collected input is output 
if Arguments 

i## channel The channel to read from 

## Results 

dt Global variable State_$channel is modified. 

df Initially starts with status == "Waiting" and data == {} 


if When data is read, status changes to "Reading", and the 
i## }=©36characters that were read are lappended to data. 
## When the word ‘DONE’ is read, collected input is output 
i## and the status is changed back to "Waiting" and the 
if «data is set to {} 
# 
proc readData {channel} { 
upvar #0 State_$channel State 
set len [gets $channel line] 


switch $State(status) { 
Waiting { 
set State(status) "Reading" 
set State(data) [list $line] 
} 
Reading { 
if {$line eq "DONE"} { 
puts "Read these lines from $State(ip): $State(data)" 
set State(status) "Waiting" 
set State(data) "" 
} else { 
lappend State(data) $line 
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socket —server acceptClient 53210 
set done 0 
vwait done 


When this code runs and a connection is made (perhaps using a telnet session to test the server) 
a new variable State_sockxX will be created. 


Script Output 
% info globals S«* 

State_sock5 

% parray State_sock5 

State_sock5 (data) = first line second line 

State_sock5 (ip) = 127.0.0.1 

State_sock5 (status) = Reading 


16.1.2 Using trace 
The trace command allows you to register a script to be evaluated when a variable or a command is 


accessed. The script can be registered to be evaluated when a variable is read, written or destroyed or 
when a command is entered, left, renamed, or deleted. 


Syntax: trace add type name ops script 
Add a script to be evaluated when an operation occurs on item name 
type The classification of the name. May be one of: 


command Register a script to be evaluated if a command is 
renamed or deleted. 


execution Register a script to be evaluated when a procedure is 
entered or exited. 


variable Register a script to be evaluated when a variable is 
read, modified or deleted. 


name The name of the item having a trace script added to it. 


ops The operation that can happen to name. When this operation occurs 
script will be evaluated. 


The trace command allows a variable to be used to control execution flow. In a process control 
environment, you might put a trace on a fai lureCount variable to cause an analysis (and perhaps 
correction) procedure to be invoked whenever there is a new failure. 

The code below shows the skeleton for a small adventure type game. It has three locations defined, 
and two commands: go and teleport. The go command will allow a player to move in a defined 
direction, while the te] eport command allows a player to move directly to any location. 

The trace command is used to cause the description procedure to be invoked whenever the 
playerl(location) variable is modified. Using trace instead of invoking the description pro- 
cedure directly from the go and teleport procs reduces the coupling between the procedures that 
manipulate the data (go and teleport) and the user interface description code. 
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The upvar command is used to map the playerl variable to the myState variable. This is a 
hook to allow this skeleton to be used for a multi-player adventure game with different variables for 
playerl, player2, etc. 

Note that this example demonstrates how to use trace, not necessarily the best way to write an 
adventure game. In particular, using eval to process user input is very dangerous. A user might type 
in acommand like "exec rm -rf /*", for instance. The interp command is discussed later in this 
chapter. 


eee 
Example 3 


Using Trace to Trigger a Procedure 


## Index is a location 
# Value is a list of direction/new location pairs 


array set places { 
house {up roof down basement} 
roof {down house} 
basement {up house} 


} 


## Description to print for locations 

array set descript { 
house {You are inside a single room house} 
roof {You are on the roof. Look at those clouds!} 
basement {You are in the basement. It’s spooky here.} 


} 


it Print the description and possible moves. 
proc describe {name index operation} { 
global places descript 
upvar $name myState 


puts "\n$descript($myState(location) )" 


foreach {direction destination} $places($myState(location)) { 
puts "You can go $direction (to the $destination)" 


} 


# Teleport to a destination 
proc teleport {destination player} { 
upvar $player myState 
global places 
if {Linfo exists places($destination) ]} { 
set myState(location) $destination 


} 
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Go in a direction 

oc go {direction player} { 
global places 

upvar $player myState 


array set moves $places($myState( location) ) 


if {!Linfo exists moves($direction) ]} { 

puts "You can’t go $direction from $myState(location)" 
} else { 

set myState(location) $moves($direction) 


Place a trace on the player variable to invoke ‘describe’ 


ace add variable playerl(location) write describe 


nitialize the player to the house 
The describe procedure will be invoked by trace 
playerl(location) house 


Loop forever reading and evaluating commands. 


jle {1} { 

puts —nonewline "Now what? " ; flush stdout 
set cmd [gets stdin] 

eval $cmd playerl 


.3 Using after 


The after command can cause a program to pause (perhaps to synchronize with some hardware) or 
can schedule a script to be evaluated after a delay. 


This is the syntax which will cause a script to pause for a given number of milliseconds: 


Syntax: after ms 


Pause for $ms milliseconds 
ms Time in milliseconds 


This syntax will schedule a script to be evaluated after $ms milliseconds have elapsed. The mainline 
script will continue running after this command is evaluated. 
The script that is scheduled to be evaluated in the future will be run from the event loop, so it is 
important that the main script eventually pause to enter the event loop. If the script is being evaluated 
by tclsh this is commonly done with the vwait command. If the script is being evaluated by wish 


the event loop is entered whenever there is no procedure being evaluated. 
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Syntax: after ms script 
Schedule $script to be evaluated after $ms milliseconds have elapsed and 
continue processing the current script. 
ms Time in milliseconds 


script A script to evaluate. 


A procedure can be invoked at intervals using the after command. The next example shows a 
heartBeat procedure that will send a short message to a remote site every 20 seconds. 


3 _—_AJ]A> A \AAAAAAAAp]$AAAAADADAhAhaoa 
Example 4 
A Repeating Procedure 
proc heartBeat {socket} { 
puts $socket "active" 
flush $socket 
after 20000 heartBeat 


The after command places the heartBeat procedure in the list of events to be processed. 
The heartBeat command is not recursive—it exits after each evaluation and a new procedure is 
created when the timer expires. 


1.4 Using bind 
The bind command is used by the Tk extension to bind an action to an event that occurs on a window. 
This is the mechanism behind the behavior of buttons, scrollbars and other interactive widgets. 


You can add new actions to existing widgets with the bind command. To assign a binding to a 
window, use this syntax: 


Syntax: bind tag event script 
tag An identifier for the widget. May be a class of widget (Button), an 
individual widget (.myButton) or the word a11 to bind to all 
widgets in the application. 
event An X-Windows event which will activate the binding. 
script A script to evaluate when the event occurs. May include % identifiers 
to allow the window system to pass data to the script. 


The example below adds a binding to a button to display a help message when you right-click on it. 


eee 
Example 5 
Adding New Functionality to a Button 


if Create an exit button 
button .exit —text "Exit" —command exit 


i## Add a special binding to this button. 
bind .exit <ButtonRelease—3> {tk_messageBox —type ok \ 
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—message "Clicking this button will exit, losing all your work"} 


grid .exit 


= 
16.1.5 Tel Interpreters 


Most Tcl applications use a single Tcl interpreter. The Tcl library supports creating multiple interpreters 
within the same executable. Each interpreter has its own set of procedures, global variables, channels, 
etc. although they share the event loop and view of the file system. 

A new interpreter can be a full-featured interpreter, just like the primary interpreter, or it can be 
a safe interpreter. A safe interpreter is the same as a normal interpreter except that all the commands 
that can interact with the operating system have been removed. Safe interpreters cannot open files or 
sockets, perform exec commands, etc. 

Multiple interpreters can be used: 


e to provide a separate environment for multiple copies of procedures that each have their own 
state. For example, an email server can use a separate interp for each mail message being read. 
This lets each interp maintain a separate state for what may be a complex set of interactions with a 
remote client. 

¢ to provide a safe environment for running scripts or commands received from untrusted sources. 
This use is common for Agent style programs or client/server applications that interact with 
unknown/untrusted entities. 


New Tel interpreters are created by an existing interpreter and have a master-slave relationship 
with the creator. A master interp can create multiple slaves, and each slave can be a master to multiple 
slave interps, creating a tree of interps rooted at the original interpreter. 

Each interpreter is named as a rooted list. For slaves of the primary interpreter, just the name of 
the interpreter is sufficient. Slaves of slaves are named from the primary interpreter down. If a slave 
interpreter named aa is created, and then a slave of aa named Db is created, the new slave would be 
named {aa _ bb}. 

Interpreters are created and manipulated using the interp command. This command has a lot of 
features and a lot of power. This section will introduce a few of the capabilities. Reading the man page 
will provide more details. 

The interp create command will create a new slave interpreter. 


Syntax: interp create ?-safe? ?--? ?name? 

Create a new interpreter. Optionally may be a safe interpreter and 

may have a specific name defined. 

-safe Make this a safe interpreter — one that cannot interact with the 
file system, networks or operating system. 

ee Marks the end of options. 

name An optional name for this interp. Default names resemble 
interpO, interpl, etc. 


When a new interpreter is created, a new command with the same name is created in the parent 
interpreter. A master can interact with a slave using that name, or the interp eval command. 
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Syntax: interp eval name script 
Evaluate script in the named interp 
name The name of a slave interpreter. 
script The script to evaluate in that interpreter. 
This code snippet creates three interpreters. The interpreter aa is a slave of the primary interpreter. 
The bb and cc interpreters are slaves of aa. This snippet shows a few of the ways that interpreters 


can be created and how code can be evaluated in the slave interpreters using the interp eval or the 
interpreter commands made by interp create. 


———————————————— eee ee ee eee 
Example 6 


Evaluating Code in a Slave Interpreter 


## Create a slave of the primary interp 
interp create aa 


if Create bb as a slave of aa 
aa eval {interp create bb} 


if Create cc as a slave of aa 
interp create {aa cc} 


## This sequence returns 3 
interp eval aa {set ax 1} 
aa eval {expr {$ax + 2}} 


## This sequence returns 4 
interp eval {aa bb} {set bx 2} 
aa eval {bb eval {expr $bx+2}} 


## This is an error 

i## cc is a command in the aa interp 

# it is not visible from the primary interpreter 
{aa cc} eval {set cx 3} 


To revisit the simple adventure game described in Section 16.1.2, we can use a safe interpreter to 
accept data from a user and evaluate the commands. The safe interpreter is a sandbox that can interact 
with the user, but not with anything else on the system. 

The interp transfer command will move an open channel from one interpreter to another. This 
can be used to accept a connection in the main Tcl interpreter, create a new safe interpreter, and then 
transfer the channel to the new interpreter. The new interpreter can interact with that channel, but not 
with any other channel including stdin and stdout. 

Syntax: interp transfer primaryInterp channel destInterp 
Transfer channel from the primary Interp interpreter to a dest Interp. The 
destination may be a safe interpreter. 


primaryInterp The interpreter in which the channel currently exists. 
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channel The channel to be moved to a new interpreter. 


destInterp The interpreter to receive the channel and commands to 
interact with the channel. 


This example shows using the interp eval and interp transfer commands to implement 
the game in the previous example in a safe manner as a client/server game. 


rr 
Example 7 
Using a Safe Slave with a Socket 
if The defineGame string contains the basic information 
set defineGame { 
i## Index is a location 
i## Value is a list of direction/new location pairs 
array set places { 
house {up roof down basement} 
roof {down house} 
basement {up house} 


} 


## Other variables and procs ellided to 
i## make the new code more visible. 


## Go in a direction 

proc go {direction player channel} { 
global places 
upvar #0 $player myState 


array set moves $places($myState( location) ) 


if {!Linfo exists moves($direction) ]} { 

puts $channel "You can’t go $direction from $myState(location)" 
} else { 

set myState(location) $moves($direction) 


} 


i## proc accptSock {channel ip port}-— 

if Accept a socket connection 

if Arguments 

if channel The channel assigned to this new connection 
# = =ip The IP address of the client socket 

## = port The port assigned to this connection 


iF 
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## Results 
dt =6Creates a new safe interp and initializes it to 
i## =3=oplay a simple adventure game. 


proc accptSock {channel ip port} { 
global sock 
global defineGame 


set sock(ch) $channel 


i## Create a new save interpreter 
set ni Linterp create —safe] 


# $id will hold the name of the player state 

# variable. It will be used to hold state within 
i the slave interpreter. 

set id player_$ni 


i## Transfer the channel to the slave. 
interp transfer {} $channel $ni 


it Send the variable and procedure definitions to 
## the new interpreter 
$ni eval $defineGame 


## Define a readData procedure in the new interp 
$ni eval Llist proc readData $channel \ 
"eval \Lgets $channel\] $id $channel"] 


i## Assign a fileevent to cause readData to be evaluated 
## when there is data to be read. 
$ni eval [list fileevent $channel readable \ 

"readData $channel"] 


if put a trace on the player state variable’s 
# location index 
$ni eval [list trace add variable ${id}( location) \ 
write "describe $channel" ] 


# Initialize the player to the house 

if The describe procedure will be invoked by trace 
## within the slave interpreter 

$ni eval [list set ${id}( location) house] 


} 


socket —server accptSock 12345 
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Each running application is a process. It has an identity within the operating system and is allocated 
memory, file descriptors and is provided with timeslices for operation. If you need to run multiple 
copies of an application, you can create multiple processes. 

The downside of multiple processes is that creating a process is fairly expensive. The executable 
binary must be read from the disk, new entries must be created in the process table, etc. If the processes 
need to interact with each other, they need to do this through the operating system using pipes, sockets 
or other IPC support, which is also expensive. 

For applications like a mail or web server that need a new environment for each client the cost of 
creating a new process is too high. A mail or web server would not be useful if it needed to read the 
mail server or web server code from disk each time a new email or HTTP request arrived. 

A thread provides an independent state for an application within the application. A thread has its 
own stack and variables (much like a process), but shares the system interface with other threads in a 
process. It does not need to read the executable code from the disk and does not need a new entry in the 
operating system process table. Communications between threads can be handled within an application 
without needing operating system calls. 

Most modern operating systems (Windows, Linux, MacOS) and languages (Java, C++, C, etc.) sup- 
port creating threads within an application. The library calls to create threads vary between operating 
systems. As with other platform specific features, Tcl provides a platform neutral approach to creating 
threads at both the script and compiled code layer. 

The core Tcl interpreter is thread-safe. A multi-threaded application that embeds the Tcl interpreter 
can create and evaluate multiple threads. Using threads at the “C” layer is discussed later in this chapter. 
This section will introduce the thread basics. The man page provides more options and details. 

You can create true multithreaded applications with pure Tcl if the application loads the Tcl 
Thread package. The Thread package is available with the Tcl source code files at http:// 
sourceforge.net/projects/tcl/files/Thread Extension/ 

The Tcl model for threading is to have one or more interpreters per thread. Each thread must have 
its own interpreter. The Thread package automatically creates a new interpreter for each thread that is 
created. 

Since each thread uses a separate interpreter, each thread has a completely separate environment, 
with its own procedures, global variables, etc. Each new thread is initialized with the default set 
of global variables and basic commands, but the new thread is not cloned from a previous thread. 
Each new thread must explicitly load any special packages, procedure definitions, and so forth, just as 
a non-threaded Tcl application needs to load packages, etc. 

The basic actions for using a thread are: 


thread: :create Create a new thread. 


thread: :send Evaluate commands within a thread. 
thread: :eval Evaluate commands within a thread. 
thread: :wait Causes a thread to enter the event loop. 


thread::release Free a thread. 


Syntax: thread::create ?-joinable? ?-preserved? ?script? 
Create a new thread. Optionally include a command for the new thread to evaluate 
immediately. Returns a unique identifier string for this thread. 
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-joinable Creates a joinable thread. A joinable thread can be joined to 
another thread which will block until the joinable thread exits. A 
joinable thread must be joined before it exits to avoid memory 
leaks. 


-preserved Preserve this thread even after it has evaluated a script. By 
default, if ?script is present, the new thread evaluates the 
script and exits. 


script A script to be evaluated immediately. This is non-blocking. The 
thread: :create command will return immediately and 
continue evaluating commands in the parent thread. When the 
new thread has completed evaluating the commands it will exit 
unless the thread: : wait command is evaluated in the new 
thread. 


Just creating a thread is not usually of much use. Your application will need to communicate with 
the thread, either to send it data to process or receive results. 
The two commands for communicating between threads are thread: : send and thread: : eval. 


Syntax: thread::send ?-async? ?-head? threadID script 
?variableName? 
Send a string to be evaluated to a thread. By default, wait for the evaluation to be 
complete before returning. 


-async The thread: : send command returns immediately 
instead of waiting for the script to complete 
processing. This option is useful for scripts that 
create more threads to communicate directly to the 
parent thread. A parent thread can use vwait to wait 
for the target thread to complete processing while 
allowing a GUI in the main thread to stay active. 


-head Force this script to the head of the event queue. 


threadID A thread identifier, as returned by 
thread: :create. 


script A script to be evaluated in the target thread. 


variableName The name of an optional variable to receive the 
results of the script. 


The next example shows how to create a thread and send it scripts to process. The first script sent 
to this thread creates a procedure named showInfo which will pause for 2 seconds (to simulate a task 
that takes time to complete) and will then print out an identifier string and the elapsed time since the 
application started. 

The loop sends eight scripts to the thread, alternating between the normal send and adding the 
-head option. The thread: :send command sends messages to the thread, which are placed on the 
thread interpreter’s event queue and evaluated in the order that they are removed from the queue. 
Using the -head flag causes a message to be placed first on the queue, delaying the messages that 
were already on the queue. 
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By default, the thread: :send command will block until it has finished being evaluated. If the 
thread: :send commands in this example did not use the -async option, they would block, and 
there would never be more than one script in the event queue, and the scripts would be evaluated in the 
order they are sent, instead of stacking them on the event queue. 


ooo ——n— —  y»-Ee 
Example 8 


Sending Messages to a Thread 


package require Thread 
set t [thread::create] 


set procDef {proc showInfo {string} { 
global initial 


after 2000 
puts "$string Elapsed Time: [expr [clock seconds] — $initial]" 
} 


} 
thread::send $t $procDef 
thread::send $t "set initial [clock seconds]" 


for {set i O} {$i < 4} {incr ji} { 
thread::send —async $t "showInfo $7" 
thread::send —head —async $t "showInfo {$7 HEAD}" 
} 
puts "Completed Loop" 
set done 0 
vwait done = 


The output generated by this application looks like this: 

Completed Loop 

Elapsed Time: 2 

HEAD Elapsed Time: 4 

HEAD Elapsed Time: 6 

HEAD Elapsed Time: 8 

HEAD Elapsed Time: 10 

Elapsed Time: 12 

Elapsed Time: 14 

Elapsed Time: 16 


WrHrR OF NM WwW OO 


The first script placed on the stack is showInfo 0. The event queue will be processed before 
the next thread: :send is evaluated. When the event queue is processed the thread will remove the 
showInfo 0 message from the event queue and start evaluating it. 

While the thread is processing that script, the primary thread is sending the rest of the showInfo 
commands. The thread: : send messages using the - head option are placed at the head of the list, 
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while those without the - head option are placed at the end. This makes the order of evaluation the last 
-head message first, and the last default order message last. 

The previous example ended with a vwait command. This command was used to force the Tcl 
interpreter to enter the event loop, rather than exiting immediately, before the thread had time to eval- 
uate any of the scripts. You need to abort this tclsh application from the operating system with a 
Control-C or by closing the task’s parent window. 

A better solution is to wait for the secondary thread to complete and then exit the primary thread. 

The thread: :create -joinable, thread: :joinand thread: : release commands provide 
this facility. 

The - joinable flag to thread: : create command creates a thread that will have its fate joined 
with another thread. The thread: : join command joins the current thread to a joinab/e thread. 


Syntax: thread::join threadID 
Wait for the identified thread to exit before continuing execution. 
threadID A thread identifier, as returned by thread: : create 


Once a thread has evaluated the thread: : join command, it will block until the joined task exits. 

Like Tcl variables, a Tcl thread contains a reference counter. When the reference counter reaches 0, 
the thread exits. The thread: : release command releases a reference to the thread by decrementing 
the reference counter. 

The next example uses the thread: : send with and without the - head option to print a sentence 
in a non-obvious order. The thread: : release command is sent last, putting it at the end of the 
scripts to be evaluated. 

After all the calls to showString have been evaluated, the command is evaluated and the sec- 
ondary thread releases itself and exits. This allows the thread: : join command to continue and the 
primary thread evaluates the final puts "end." command before it exits. 


OOOO —-.:.—n—n—n— aay»: 
Example 9 


Joining Two Threads 
package require Thread 


set t [thread::create —joinable] 


set procDef {proc showString {string} { 
after 1000 

puts —nonewline "$string " 

} 

} 


thread::send $t $procDef 


foreach word {Atropos in the} { 
thread::send —async $t "showString $word" 


} 


foreach word {threads all cuts } { 
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thread::send —head —async $t "showString $word" 


} 

puts "The Greeks believed that" 
thread::send $t {thread::release} 
thread::join $t 

puts "end." 


The output of this example looks like this: 
The Greeks believed that 
Atropos cuts all threads in the end. 

In order for a thread to use thread: :send, it needs to know the thread ID of the target thread. 
This is simple when the primary thread is sending data to a secondary thread, since the thread ID is 
returned by the thread: : create command when the thread is created. 

However, a secondary thread does not receive any information to identify the thread that created 
it. In order to send data from a secondary thread to a primary thread, the script needs to discover the 
thread ID of the primary thread. 

The thread::id and thread: :names commands will return the thread identifier of the current 
thread, and a list of all threads. 


Syntax: thread::id 
Return the identifier of the current thread 


Syntax: thread: :names 
Return a list of all the thread identifiers 


The next example shows how a primary thread can send its thread ID to secondary threads so that 
they can can communicate back with a primary thread. The example creates a simple GUI with a button 
to start new threads, a label to show how many threads currently exist, and a set of labels that display 
the contents of a variable. The value of the variable is modified by the secondary threads. 

The calls to thread: : create include a script to be evaluated in the secondary thread. The script 
contains a for loop that pauses and sends a message to the primary thread, using the thread ID provided 
by the primary thread. The message to the primary thread modifies the contents of the global variable 
that is used as a - textvariable for the labels. When the for loop is complete, the secondary thread 
exits. 

The updateThreadCount is scheduled to run every second using the after command (see 
Section 16.1.3). It uses the thread: :names command to count the currently active threads, again 
updating a global variable that is used as a - textvariable in the label. 


—— ee OOO 
Example 10 


Sending Information to a Primary Thread 
package require Thread 


proc createThread {} { 
global tnum var 
incr tnum 
label .1$tnum —textvariable var($tnum) 


16.3 Embedded Tcl Interp and Threading 657 


set cmd [format {for {set i 0} {$1 < 10} {incr i} { 
thread::send %s "set var(4%s) $i" 
after 1000 
}} Cthread::id] $tnum] 

set id [thread::create $cmd] 

label .1ltn$tnum —text $id 

grid .ltn$tnum .1$tnum 


} 


proc updateThreadCount {} { 
global threadCount 
set threadCount Lllength [thread::names]] 
after 1000 updateThreadCount 

} 


button .b —command {createThread} —text "New Thread" 
grid .b 


label .1t —text "Threads Running:" 
label .ltc —textvariable threadCount 
grid <1 ite 

updateThreadCount 


set tnum 1 


These three images show the initial display, what the display looks like while two threads are 
running, and what it looks like after the for loops in the threads have been completed and the thread 
has exited. 

The count of threads is always at least 1, since the primary thread will always be present. 


Hew Thread | Hew Thread | 


hreads Running: 3 hreads Running: 1 
New Thread | tidOxb67a3b70 5] | tidOxbé7aab70 9 
hreads Running: 1 tidOxb5fa2bfo 2 tidOxb5fa2bro 69 


Start Running Complete 


3 EMBEDDED TCL INTERP AND THREADING 


This section will introduce the basics for creating threads within a compiled application that embeds 
the Tcl interpreter. It will introduce basic thread concepts but is not a complete guide to thread pro- 
gramming. There are many styles of threaded application architectures. If you are adding Tcl threads 
to an existing application you will probably need to study the application’s thread behavior as well as 
Tcl’s thread support. 
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Many compiled systems use multiple threads. The Tcl interpreter has been thread-safe and the Tcl 
library has supported creating new threads since version 8.1. 

Each thread that uses a Tcl interpreter must include its own copy of an interpreter. You can’t load a 
script into one thread and then run it in another. A thread may contain multiple interpreters. 

Some applications (including sendmail and the Apache web server) create threads within the main- 
line compiled code and pass a thread identifier to a user-provided function. In this case, you can use the 
Tcl_CreateInterp function (described in Section 15.5) to create an interpreter within that thread. 

If your application is standalone it can create a new thread with the Tcl_CreateThread function. 


Syntax: Tcl_CreateThread (idPtr, func, clientData, stack, flags) 
Creates a new thread in a platform-neutral manner. Passes control to the 
defined function to initialize the thread. 
idPtr A pointer to a Tcl_ThreadId variable which will receive the 

thread id of the new thread. Tcl_ThreadId is a platform neutral 
datatype that can be used with other Tc1_Thread calls. 


func A compiled function that will initialize the thread. 

clientData A pointer to arguments that will be passed to the initialization 
function. 

stack Some systems allow run-time definition of the stack size. The 


safest and most platform-neutral value to provide here is 
TCL_THREAD-STACK_DEFAULT. 

flags A set of flags to define the new thread. The two supported 
options are: 


TCL.-THREAD_NOFLAGS There is no special behavior for this thread. 

TCL_THREAD_JOINABLE This thread can be joined to another thread to con- 
trol execution. One common use of this is to have one 
thread wait for a joined thread to complete execution 
and release a shared resource. 


When Tcl1_CreateThread is called, it creates a new thread and passes control to func the function 
declared in the arguments. The func function will be running within the newly created thread. This 
function should create and initialize the Tcl interpreter as described in Section 15.5. 

Once a new thread is created the main thread need not interact with it. If the main thread does 
nothing, it will simply exit after creating the new thread, at which point the entire application, including 
the new thread, is gone. 

One solution to this issue is for the main thread to wait for the subordinate threads to exit. The 
Tcl_JoinThread command will wait for a given thread to exit, or return immediately if that thread 
has already exited. 


Syntax: void Tcl_JoinThread (threadID, result) 
Waits for the thread defined by threadID to exit. 
Tcl_ThreadId threadID The thread id set by Tc]l_CreateThread(). 


int *result A pointer to an integer for the threads exit value. This 
may be NULL if you don’t need to examine the return. 
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The next example extends the embedded application described in Section 15.5 to run a number of 
threads. The number of threads to create is defined by the user at run time using the command line 
argument. The bulk of the previous main function has been moved to the createThread function 
and replaced with loops to create new threads and wait for them to exit. 


$$ 
Example 11 
mainThread.c 

dFinclude <stdlib.h> 

dFinclude <math.h> 

dFinclude <tcl.h> 

dFinclude <tk.h> 


#Finclude "./factorcountInt.h" 
/*. 
* int createThread (char xargv[])—— 
* Create a new thread with a Tcl interpreter in it 
* Initialize the interp and start it running a 
* predefined script. 
x Arguments: 
* argv array of arguments from the command line 
* 
* Results: 
* Returns TCL_OK or TCL_ERROR 
* 
* Side Effects: 
* New thread, etc. 
*/ 

int createThread (char *argv[]) { 

Tcl_Interp *interp; /* Interpreter for application. x/ 


int rtn; 


// Create the interp and initialize it. 
Tcl_FindExecutable(argv[0]); 


interp = Tcl_CreateInterp(); 


if (Tcl_Init(interp) == TCL_-ERROR) { 
printf("FAIL TCL_INIT\n"); 
return TCL_ERROR; 


} 


if (Tk_Init(interp) == TCL_ERROR) { 
printf("FAIL TK_INIT\n"); 
return TCL_ERROR; 


} 


// Add the factorcount command 


660 CHAPTER 16 Applications with Multiple Environments 


// factorcount_Cmd is defined in factor.c 
Tcl_CreateObjCommand(interp, "“factorcount", 
Factorcount_Cmd, (ClientData) NULL, NULL); 


// Run the Tcl script file — hardcoded for myScript.tcl 
rtn = Tcl_Eval(interp, "source myScript.tcl"); 
if (rtn != TCL_OK) { 

printf("Failed Tcl_Eval: %d \n’s\n", rtn, 


Tcl_GetVar(interp, "“errorInfo", TCL_GLOBAL_ONLY)); 
exit(-1); 


main(int argc, char xargvl]) { 
// function variables 


int i; // Counter 
int threadCount; // Number of threads to creats 
// read from command line 
Tcl_ThreadId xthreadID; // Returned by Tcl_CreateThread 


sscanf(argvL1l], "%d", &threadCount) ; 
threadID = calloc(threadCount, sizeof(Tcl_ThreadId)); 


for (i=0; i< threadCount; i++) { 

if (TCL_OK != Tcl_CreateThread(&threadIDLil, 
createThread, argv, TCL_THREAD_STACK_DEFAULT, 
TCL_THREAD_JOINABLE)) { 
printf("Failed to create thread #%d\n", 7); 
Tcl_Exit(-1); 


} 
// Wait for all threads to exit. 


for (i=0; i< threadCount; i++) { 
Tcl_JoinThread(threadIDLi], NULL); 
} 


// Use Tcl_Exit() instead of exit() to 
1 ensure Tcl closes cleanly. 
Tcl_Exit(0); 
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The script for this example uses the Thread package to display the thread identifier in the 
decoration. 


ee. en 
Example 12 
myScript.tcl 


lappend auto_path /opt/ActiveTcl—8.5/lib/tcl8.5/ 
package require Thread 


wm title . [thread::id] 


set done 0 
load ../factorcount/libfactorcount.so 


label .11 —text "Enter Number:" 
entry .el —textvar product 


button .bl —text "go" —command {set answer [factorcount count $product ]} 
button .b2 —text "done" —command {set done 1} 


label .12 —text “Factors:" 
label .13 —textvar answer 


grid .11 .el 
grid .bl .b2 
Grid. x12 13 


vwait done 


Script Output 
./factorsThread 4 


tidOxb6b3bbs0 tid0xb753cb90 
Enter Number: 123456789 Enter Number: 987654321 


Factors: Factors: 17 


tidOxb613ab390 tidOxb7f3dbs0 


Enter Number: 12345 Enter Number: 1234567891 


Factors: Factors: 1 
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The example requests 4 threads, which run concurrently (within constraints of your CPU). The for 


loop in the main function keeps all of the windows present until the last thread has exited. 


16.4 BOTTOM LINE 


Tcl supports several techniques for controlling several application environments within a single 
interpreter. 

The event loop can be used to invoke Tcl procedures with information about the environment that 
caused the event. 

Slave interpreters contain a private copy of a Tcl interpreter. 

Tcl supports creating threads at both the script and compiled code layer. 

The fi 1]eevent command will invoke a script when data is available on an IO channel. 
fileevent channel direction ?script? 

The upvar command can map a global state variable into a procedure scope. 

upvar ?level? variableName newName 

The trace command can be used to evaluate a procedure when a variable is modified. 

trace add type name ops script 

The bind command will bind a script to a widget and will invoke that script when a specific event 
occurs. 

bind tag event script 

A slave interpreter is created with the interp create command. 

interp create ?-safe? ?--? ?name? 

Tcl interpreters can be full functioned or safe. A safe interpreter has no capability to interact outside 
of the application. 

Code is evaluated within a slave interpreter with the interp eval command. 

interp eval name script 

A safe interpreter can be given access to a channel created in a full-featured interpreter with the 
interp transfer command. 

interp transfer primaryInterp channel destInterp 

Script level threading is supported with the Thread package. Commands within the Thread 
package exist within the thread: : namespace. 

A new thread can be created within a script with the thread: : create command. 

thread: :create ?-joinable? ?-preserved? ?script? 

A script can be sent to a thread for evaluation with the thread::send or thread::eval 
commands. 

thread::send ?-async? ?-head? threadID script ?variableName? 

A new thread can be created at the C layer using the Tcl_CreateThread function. 
Tcl_CreateThread (idPtr, func, clientData, stack, flags) 

One thread can wait for another thread to exit with the Tcl_JoinThread function. 

void Tcl_JoinThread (threadID, result) 
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16.5 PROBLEMS 


The following numbering convention is used in all Problem sections: 


Number Range _ Description of Problems 


100-199 Short comprehension problems review material covered in the chapter. They can be 
answered in a few words or a 1-5-line script. These problems should each take under 
a minute to answer. 

200-299 These quick exercises require some thought or information beyond that covered in the 
chapter. They may require reading a man page, or making a web search. A short script 
of 1-50 lines should fulfill the exercises, which may take 10-20 minutes each to 
complete. 

800-399 Long exercises may require reading other material, or writing a few hundred lines of 
code. These exercises may take several hours to complete. 


e¢ 100 What types of events will the fi 1 eevent command process? 

e 101 Can after be used to schedule a script to be evaluated in the future? 

e 102 Can a Tcl application have more than one interpreter? 

e 103 Can multiple environments be implemented with namespaces or TclOO class? 
e 104 Can anew thread be created within a Tcl script? 

e 105 Why would an application need to support multiple sets of state? 


e 200 Write an IP server that will accept two socket connections and let two persons play a game of 
Tic-Tac-Toe against each other. The server should accept commands like: 
X # Place an X at location # 


0 # Place an O at location # 

It should return the opposing players turn with a similar response, and tell players who has 
won when the game is complete. 

Use fileevent to read input from the players. Use an extra argument to the getData script 
to distinguish the two players. 


e 201] Rework the previous example to support multiple pairs of players. This will require a way to 
track multiple games. Use the upvar technique to map global state variables to individual games. 


e 202 Rework Exercise 200 to support multiple pairs of players. This will require a way to track 
multiple games. Use a separate slave interpreter to hold each game. 


e 300 Add a Tk client to the game built in Exercise 200 to show the game board and allow the 
player to click the location for their move. 
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301 Rework Exercise 200 to support multiple pairs of players. This will require a way to track 
multiple games. When a pair of players joins create a new thread for that game using the Thread 
package. 


302 Write a Tcl script which will spawn N threads. Each thread will get a unique random number 
seed and will then simulate a game of Tic-Tac-Toe with two players choosing random locations 
for the moves. Display the boards and seed using a GUI similar to that developed in Exercise 300. 


303 Modify the scripts written in Exercise 302 to be run from a compiled main. c which will 
create N threads and then play the simulated games of Tic-Tac-Toe. 


CHAPTER 


Extensions and Packages 


The previous chapters described building Tcl packages and C language extensions to Tcl. Using these 
techniques, you can create almost any application you desire. 

In many cases your applications will require features that have already been developed. You can 
save time by using existing extensions and packages for these features. Using existing extensions not 
only saves you development time but reduces your maintenance and testing time. 

This chapter provides an overview of a few extensions and packages. It is not possible to cover all 
of the extensions and packages written for Tcl. The Tcl FAQ (frequently asked questions) lists over 
700 extensions, and more are being written. Before you write your own extension, check to see if one 
already exists. 

The primary archive for Tcl extensions and packages is www.sourceforge.net. Most extensions are 
also announced in comp.lang.tcl or comp.lang.tcl.announce. You can use the Google News 
Search engine (www. google.com/advanced_group-search) to limit your search to those newsgroups. 
Finally, many of the extensions are described in the Tcl/Tk FAQ (www.purl.org/NET/Tcl- FAQ), and 
discussed on the Tcler’s Wiki (Attp://wiki.tcl.tk/). 

Many packages and extensions are grouped together in the tcl1ib group. The tcllib col- 
lection is provided as part of the ActiveState Active-Tcl distribution and is also available at 
http://www.sourceforge.net/projects/tcllib. 

Although extensions can save you a great deal of development time, there are some points to 
consider when using extensions and packages. 


e Extensions tend to lag behind the Tcl core. 

Most of these packages are developed by Tcl advocates who work in their spare time to maintain 
the packages. It can take weeks or months before they have time to update their package after a 
major change to the Tcl internals. 

Commercial extensions can also lag behind the core. Frequently, a commercial user of Tcl will 
decide to freeze their application at a particular level, rather than try to support multiple levels of 
code at their user sites. 

In particular, the change from Tcl 7.6 to Tcl 8.0 introduced some API changes requiring enough 
rewriting that some less popular extensions have not yet been ported beyond revision 7.6. 

Most popular and commercial packages, however, have been updated to take advantage of the 
8.0 improvements. 
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Not all extensions are available on all platforms. 

Many packages were developed before Tcl was available on Macintosh and Windows platforms, 
and they may have some UNIX-specific code in them. Similarly, there are Windows-specific and 
Mac-specific extensions that interface with other platform-specific applications. 

All extensions may not be available at your customer site. 

Installing extensions takes time, and keeping multiple versions of libraries and extensions con- 
sistent can create problems for system administrators. Thus, the more extensions your application 
requires, the more difficult it may be for users to install your application. 

If you are writing an application for in-house use (and your system administrators will install 
the extensions you need), this is not a problem. However, if you write an application you would 
like to see used throughout your company or distributed across the Internet, the more extensions it 
requires and the less likely someone is to be willing to try it. 


If you need an extension, by all means use it. However, if you can limit your application to using 


only core Tcl or a single extension, you should do so. 


The ActiveTcl (or Batteries Included) Tcl distribution from ActiveState provides many of the pop- 


ular extensions, and is becoming the de facto standard Tcl distribution. If your application requires 
these extensions, odds are good that it will run on your client systems. 


Wrapping an application with the Tcl interpreter and required extensions to make a single exe- 


cutable module is another distribution option. Some of these options are discussed in the next chapter. 
Packages written in Tcl are more easily distributed than extensions written in C. 


Whereas many sites may not have an extension, any site that is interested in running your Tcl appli- 


cation can run Tcl packages. You can include the Tcl packages your script needs with the distribution 
and install them with your application. For example, the HTML library discussed in Chapter 11 has 
been included in several other packages, including TclTutor and tkchat. 


This chapter introduces the following packages. 

Lincr Tcl] The previous chapters have shown how object-oriented techniques 
can be used with pure Tcl. The [incr Tcl] extension provides a 
complete object-oriented extension for the Tcl developer. It sup- 
ports classes; private, public, and protected scopes; constructors; 
destructors; inheritance; and aggregation. 

The newest [incr tcl ] also includes features from snit includ- 
ing type, widget, and widget adapters. 

expect expect automates procedures that have a character-based interac- 
tion. It allows a Tcl script to spawn a child task and interact with 
that task as though the task were interacting with a human. 


Tclx This is a collection of new Tcl commands that support system 
access and reduce the amount of code you need to write. Many 
of the TclX features have been integrated into the more recent 
versions of Tcl. 


tdbc The tdbc (Tcl DataBase Connectivity) package provides a server- 
neutral view of the various SQL database engines. This package 
replaces the older single-engine extensions like OraTcl, SybTcl, 
mysqlitcl, tclsqlite, etc. 
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Rivet Rivet is an Apache module that supports generating dynamic content 
with Tcl scripts. 


BWidgets The Bwidgets package provides several compound widgets and ver- 
sions of standard Tk widgets with extended features. This is a pure 
Tcl package that can be used on multiple platforms. 


Img This extension adds support for more image file formats to the Tcl 
image object. 


17.1 [incr Tcl] 


Language C 
Primary Site httpz://inertcl,.sourcerorge .net/ 
Contact arnulf@wiedemann-pri.de, Arnulf Wiedemann 


Tcl Revision Supported Tcl: 7.3-8.6 and newer 
Tk: 3.6-8.6 and newer 
Supported Platforms UNIX, MS Windows, Mac OSX 


Mailing List incrtcl -users-request@lists.sourceforge.net 
with a subject of: subscribe 


Other Book References Tcl/Tk Tools 
[incr Tcl/Tk] from the Ground Up 


[Incr Tcl] is to Tcl what C++ is to C, right down to the pun for the name. It extends the base Tcl 
language with support for the following. 


e Namespaces. 
e Class definition with: 
e Public, private, and protected class methods 
e Public, private, and protected data 
e Inheritance 
e Delegation 
e Aggregation 
e Constructors 
e Destructors 
e Variables attached to a class rather than a class instance 
e Procedures attached to a class rather than a class instance 


The namespace commands were first introduced into Tcl by Lincr Tcl]. The [incr Tcl] 
namespace command has the same basic format as the namespace command in Tcl 8.0. One dif- 
ference is that [incr Tcl] allows you to define items in a namespace to be completely private. A 
pure Tcl script can always access items in a Tcl namespace using the complete name of the item. 
Previous chapters showed how you can use subsets of object-oriented programming techniques 
with Tcl. With Lincr Tcl] you can perform pure object-oriented programming. The following 


668 CHAPTER 17 Extensions and Packages 


example is adapted from the [incr Tcl] introduction (itcl-intro/itcl/tree/tree2.itcl). 
It implements a tree object. 

There are man pages and MS Windows help files included with the [incr Tcl] distribution. 
A couple of commands used in this example include class and method. The class command defines 
a Class. In the example that follows, this defines a Tree class with the private data members key , 
value, parent, and children. 


Syntax: class className { script } 
Define an [incr Tcl] class. 
className A name for this class. 


{script} A Tel script that contains the commands that define this class. These 
commands may include procedure (method) definitions, variable 
declarations, and inheritance and access definitions. 


The class methods are defined with the method command and can be defined either in line (as 
the methods add, clear, and parent are defined) or similarly to function prototypes (as the get 
method is defined). When a method is defined as a function prototype, the code that implements the 
method can be placed later in the script or in a separate file. 


Syntax: method name { args } { body } 
Define a method for this class. 
name The name of this method. 
args An argument list, similar to the argument list used with the proc 
command. 


body The body of this method. Similar to the body of a proc. 


eee eee eee 
Example 1 
Script Example 


puts [package require Itcl] 


itcl::class Tree { 

private variable key "" 
private variable value "" 
private variable parent "" 
private variable children "" 


constructor {n v} { 
set key $n 
set value $v 


} 


destructor { 
clear 


} 


method add {obj} { 
$obj parent $this 
lappend children $o0bj 


} 
method clear {} { 
if {$children != ""} { 
eval delete object $children 
} 


set children {} 
} 


method parent {pobj} { 
set parent $pobj 
} 


method contents {} { 
return $children 


} 


public method get {{option —value}} 


} 


itcl::body Tree::get {{option —value}} { 
switch — $option { 
—key { return $key } 
—value { return $value } 
—parent { return $parent } 


} 


error "bad option \"$option\ 


iF 
df USAGE EXAMPLE 
i 


it Create a Tree 
t 
Tree topNode keyO Valued 


t 

it Add two children 

t 

topNode add [Tree childNodel keyl Valuel] 
topNode add [Tree childNode2 key2 Value2] 
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i 
i## Display some values from the tree. 
tt 
puts "topNode’s children are: [topNode contents ]" 
puts "Value associated with childNodel jis \ 
[childNodel get —value]" 
puts "Parent of childNode2 is: [childNode2 get —parent]" 


Script Output 
topNode’s children are: childNodel childNode2 
Value associated with childNodel is Valuel 
Parent of childNode2 is: ::topNode 


17.2 expect 


Language C 

Primary Site http://expect.nist.gov/ 

Contact libes @nist. gov, Don Libes 

Tcl Revision 

Supported Tcl: 7.3-8.6 and newer 
Tk: 3.6-8.6 and newer 

Supported UNIX, Windows 

Platforms 

Other Book 

References Exploring Expect, Tcl/Tk Tools 


expect adds commands to Tcl that make it easy to write scripts to interact with programs that use a 
character-based interface. This includes programs such as telnet and FTP that use a prompt/command 
type interface or even keyboard-driven operations like extracting usage information from a large router. 

expect can be used for tasks ranging from changing passwords on remote systems to convert- 
ing an interactive hardware diagnostics package into an automated test system. When you load both 
the expect and Tk extensions simultaneously you have a tool that is ideal for transforming legacy 
applications that use dialogs or screen menus into modern GUI-style applications. There are three 
indispensable commands in expect. 

Spawn Open a connection to an application to interact with. 


expect Define input strings expected from the external 
application. 


exp_send Send output to the external application as if it were typed 
at a keyboard. 


Syntax: spawn options commandName commandArgs 
Starts a new process and connects the process’s stdin and stdout to the expect 
interpreter. 
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options The spawn command supports several options, including: 
-noecho The spawn will echo the command 
line and arguments unless this option 
is set. 


-open fileID The -open option lets you process 
the input from a file handle (returned 
by open) instead of executing a new 
program. This allows you to use an 
expect script to evaluate program 
output from a file as well as 
directly controlling a program. 

commandName The name of the executable program to start. 


commandArgs The command line arguments for the executable program 
being spawned. 


OOOO —_”———n—n—n— —O y_e 
Example 2 


spawn Example 


## Open an ftp connection to the Ubuntu CD repository 
spawn ftp cdimage.ubuntu.com 


Syntax: expect ?-option? patternl actionl ?-option? pattern2 
action2 ... 
Scan the input for one of several patterns. When a pattern is recognized, evaluate 
the associated action. 
-option Options that will control the matching are: 


-exact Match the pattern exactly. 
-re Use regular expression rules to match this pattern. 
-glob Use glob rules to match this pattern. 

pattern A pattern to match in the output from the spawned program. 


action A script to be evaluated when a pattern is matched. 


A$$ 
Example 3 
expect Example 
expect { 
{Name } { 
puts "Received the Name prompt" 
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Syntax: exp_send string 
Sends string to the slave process. 
string The string to be transmitted to the slave process. Note that a 
newline character is not appended to this text. 


SSS 
Example 4 
exp_send Example 

i## Download the readme file 

exp_send "get README\n" 


The exp_send command must explicitly add a newline if the command requires one. This is the 
opposite of the puts command that appends a newline unless requested otherwise. 
When expect finds a string that matches a pattern, it stores information about the match in the 
associative array expect_out. This array contains several indices, including the following. 
expect_out (buffer) All characters up to and including the characters that matched a 
pattern. 


expect_out(0,string) The characters that matched an exact, glob, or regular 
expression pattern. 


expect_out(#,string) The indices (1,string)-(9,string) will contain the 

characters that match regular expressions within parentheses. The 
characters that match the first expression within parentheses are 
assigned to expect_out(1,string), the characters that match 
the next parenthetical expression are assigned to 
expect_out(2,string), and so on. 

The Ubuntu project maintains a website from which iso images can be downloaded. The next 
example will log into that site, change to the folder for the UbuntuStudio natty release and download 
any iso images that aren’t already in the folder. 

The dialog procedure simplifies the main program flow by extracting the timeout and eof tests 
that would otherwise be needed with each expect command. 


—————————————— eee ee eee 
Example 5 


Script Example 
#lexpect 


if Open a connection to Ubuntu 
spawn ftp cdimage.ubuntu.com 


if Set the timeout for 10 seconds. 
set timeout 10000 


HAAR BAAR AAR AAR AAA AAA AAA AAA AAA AAA AAA AAA AAA AAA 
## proc dialog {prompt send }-- 


# Generalize a prompt/response dialog 
if Arguments 


i## =prompt: The prompt to expect 
# =©6osend: The string to send when the prompt is received 
## Results 
# = =No valid return 
it «Generates an error on TIMEOUT or EOF condition. 
proc dialog {prompt send } { 

expect { 

$prompt { 
sleep 1; 


exp_send "$send\n" 
} 


timeout { 
expect * 
error "Timed out" \ 
"Expected: *$prompt’. Saw: $expect_out(buffer)" 
} 
eof { 
expect * 
error "Connection Closed" \ 
"Expected: *$prompt’. Saw: $expect_out(buffer)" 


Expect "Name", send "anonymous" 
ialog "Name" anonymous 


Expect 
ialog " 


the password prompt, and send a mail address 
assword" "user@example.com" 


Change 
ialog "f 


to the natty release folder 
tp>" "cd cdimage/ubuntustudio/releases/natty/release" 


ist of the available files 
tp>" "1s" 


Get a 
ialog 


"Ef 


set files 


## Loop until a break condition is reached 
if Read lines looking for words (file names) 
## = =that end in .rpm 


while {1} { 
expect { 
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-re {([* ]xiso)} { 
if Recognized an iso file. Check to see if we 
i## already have it. 


if {!Lfile exists $expect_out(1l,string)]} { 
i## No, we don’t have this one, append it 
i## to a list to download. 


lappend files $expect_out(1,string) 
} 
} 
ftp> { 
## At the end of the file list, this is a new prompt 
break; 
} 
timeout { 
error "Connection Timed out!" 
} 
eof { 
error "Connection Closed!" 


i## We collected the prompt to find the end of the 
if *1s’ data. 
i## Send a newline to generate a new prompt. 


exp_send "\n" 


if For each file in our list of files to collect, 
df Get the file. 


foreach file $files { 
dialog "ftp>" "get $file" 
} 


Script Output 
spawn ftp cdimage.ubuntu.com 
Connected to cdimage.ubuntu.com. 
220 Ubuntu FTP server (vsftpd) 
Name (cdimage.ubuntu.com:clif): anonymous 
331 Please specify the password. 
Password: 
230 Login successful. 
Remote system type is UNIX. 
Using binary mode to transfer files. 
ftp> cd cdimage/ubuntustudio/releases/natty/release 


250 Directory successfully changed. 

ftp> ls —latr 

229 Entering Extended Passive Mode (|||48099|). 
150 Here comes the directory listing. 


ubuntustudio-—11. 
ubuntustudio-—11. 
ubuntustudio-—11. 
ubuntustudio-—11. 
ubuntustudio-—11. 
ubuntustudio—11. 
ubuntustudio-—11. 
ubuntustudio—11. 
ubuntustudio-—11. 
ubuntustudio-—11. 
ubuntustudio-—11. 


04—alternate—amd64.template 
04—alternate—amd64.iso 
04—alternate—amd64.list 
04—alternate—i386.template 
04—alternate—i386.iso 
04—alternate—i386.list 
04—alternate—amd64 .jigdo 
04—alternate—amd64.iso.zsync 
04—alternate—i386.jigdo 
04—alternate—i386.iso.zsync 
04—alternate—amd64.iso.torrent 


MD5SUMS.gpg 
MD5SUMS 
SHA1SUMS.gpg 
SHA256SUMS 
ubuntustudio-—11. 
SHA1SUMS 
HEADER. html 
FOOTER .html 
SHA256SUMS.gpg 
-htaccess 
ubuntustudio—11.04—alternate—amd64 .metalink 
MD5SUMS—metalink 

MD5SUMS—metalink.gpg 
ubuntustudio—11.04—alternate—i386.metalink 

226 Directory send OK. 

ftp> 

ftp> get ubuntustudio—11.04—alternate—i386.iso 
local: ubuntustudio—11.04—alternate—i386.iso \ 
remote: ubuntustudio—11.04—alternate—i386.iso 
Entering Extended Passive Mode (|||57878|). 
Opening BINARY mode data connection for \ 


04—alternate—i386.iso.torrent 


229 
150 


ubuntustudio—11.04—alternate—i386.iso (1560033280 bytes). 
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id 


3 TclX 
Language C 


Primary Sites http://tclx. sourceforge.net/ 
http://wiki.tcl. tk/tclx/ 
www.maths.mq.edu.au/~steffen/tcltk/tclx/ 


(TclX for Macintosh) 
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Contact markd@ grizzly.com, Mark Diekhans 
Tcl Revision Supported Tcl: 7.3-8.6 and newer 

Tk: 3.6-8.6 and newer 
Supported Platforms UNIX, MS Windows, Mac Os 
Other Book References = Tcl/Tk Tools 


The Tc1X extension is designed to make large programming tasks easier and to give the Tc1 pro- 
grammer more access to operating system functions such as chmod, chown and kil1.Tc1X contains a 
large number of new commands. Many of the best features of Tcl (sockets, time and date, random num- 
bers, associative arrays, and more) were introduced in Tc1 X. There are still many features provided by 
Tc1X that are not in the Tcl core. Tc1X features include the following. 


e Extended file system interaction commands 
e Extended looping constructs 

e Extended string manipulation commands 

e Extended list manipulation commands 

e Keyed lists 

e Debugging commands 

e Performance profiling commands 

e System library interface commands 

e Network information commands 

e Message catalogs for multiple language support (compliant with X/Open Portability Guide) 
e Help 

e Packages 


Using Tc1X can help you in the following ways. 


e Tc1X gives you access to operating system functions that are not supported by the Tcl core. Using 
core Tcl, you would need to write standalone C programs (or your own extensions) to gain access 
to these. 

e TclX scripts are smaller than pure Tcl scripts, because Tc1X has built-in constructs you would 
otherwise need to write as procedures. 

e TclX commands run faster than the equivalent function written as a Tcl procedure, because the 
Tc1X command is written in C and compiled instead of interpreted. 


The following example uses the recursive file system looping command for_recursive_g1ob to step 
through the files in a directory, and the three text search commands scancontext, scanmatch, and 
scanfile. 

The fileDict procedure in chapter 6 used the foreach, glob, and file type commands 
to build a recursive directory search procedure. The for_recursive_glob command provides these 
features in a single loop. 


Syntax: for_recursive_glob var dirlist globlist code 
Recursively loops through the directories in a list looking for files that match one of 
a list of glob patterns. When a file matching the pattern is found, the script defined 
in code is evaluated with the variable var set to the name of the file that matched 
the pattern. 
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var The name of a variable that will receive the name of each 
matching file. 

dirlist A list of directories to search for files that match the g/oblist 
patterns. 


globlist A list of glob patterns that will be used to match file names. 


code A script to evaluate whenever a file name matches one of the 
patterns in globlist. 


Many applications require searching a large number of files for particular strings. A pure Tcl script 
can perform this operation by reading the file and using string first, string match or reg- 
exp. This type of solution uses many interpreter steps and can be slow. The TclX scancontext, 
scanmatch, and scanfile commands work together to optimize file search applications. 


Syntax: scancontext create 
Create a new scan context for use with the scanf ile command. Returns a 
contextHandle. 
The contextHand/e returned by the scancontext create command can be used with the scan- 
match command to link in a pattern to an action to perform. 


Syntax: scanmatch contextHandle ?regexp? code 
Associate a regular expression and script with a contextHandle. 
contextHandle Ahandle returned by scancontext create. 
regexp A regular expression to scan for. If this is blank, the 
script is assigned as the default script to evaluate when 
no other expression is matched. 
code A script to evaluate when the regexp is matched. 
When a regular expression defined with scanmatch is recognized, information about the match 
is stored in the associative array variable matchInfo, which is visible to the code script. The 
matchInfo variable has several indices with information about the match. 
The scanfile command will examine a file’s contents and invoke the appropriate scripts when 
patterns are matched. 


Syntax: scanfile contextHandle fileld 
Scan a file for lines that match one of the regular expressions defined in a context 
handle. If a line matches a regular expression, the associated script is evaluated. 
contextHandle The handle returned by the scancontext create 
command. 


fileld A file channel opened with read access. 


Oooo —-—n—n—n—n— Oey» z= 
Example 6 


Script Example 


package require Tclx 


proc scanTreeForString {topDir pattern matchString \ 
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filesWith filesWithout} { 
upvar $filesWith with 
upvar $filesWithout without 


set with "" 
if Create a scan context for the files that will be scanned. 
set sc [scancontext create] 


if Add an action to take when the pattern is recognized 

# in a file. If the pattern is recognized, append the 

i## file name to the list of files containing the pattern 

it and break out of the scanning loop. Without the "break", 
i## scanfile would process each occurrence of the text that 
it matches the regular expression. 


scanmatch $sc "$matchString" { 

append with [file tail $filename] 
break; 

} 


it Process all the files below $topDir that match the 
## pattern 


for_recursive_glob filename $topDir $pattern { 
set fl Lopen $filename RDONLY ] 
scanfile $sc $f] 
close $f 
i## If there were no lines match the $matchString, 
## there will be no $filename in the list "with". 
## In that case, add $filename to the list of files 
# without the $matchString. 
if {Llsearch $with [file tail $filename]] < 0} { 
append without [file tail $filename] 


al 


} 
## Clean up and leave 
scancontext delete $sc 
} 
scanTreeForString /usr/src/tcl *.h Tcl_Obj hasObj noObj 


puts "These files have ’Tcl_Obj’ in them: $hasObj" 
puts "These files do not: $no0bj" 
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Script Output 
These files have ‘Tcl Obj’ in them: tclOOInt.h 
tclFileSystem.h tclOODecls.h tcl00O.h tclIntPlatDecls.h 
tclCompile.h tclInt.h tclOOIntDecls.h tclRegexp.h 
tclIntDecls.h tclIO.h tclDecls.h tcl.h 


These files do not: tclTomMathDecls.h regerrs.h 
tclTomMathIint.h regcustom.h tclTomMath.h tommath.h 
tclPort.h tclPlatDecls.h regguts.h regex.h tclUnixThrd.h 
tclUnixPort.h tommath_superclass.h tommath.h 
tommath_class.h tclWinInt.h tclWinPort.h dirent2.h 
limits.h stdlib.h fake—rfc2553.h dlfcn.h float.h 
dirent.h string.h unistd.h mpi.h mpi-—-types.h 

logtab.h mpi—config.h inffixed.h gzguts.h inftrees.h zlib.h 
deflate.h zconf.h trees.h inffast.h crce32.h inflate.h 
zutil.h gzlog.h blast.h zfstream.h puff.h ioapi.h 
mztools.h iowin32.h crypt.h zip.h unzip.h inftree9.h 
inflate9.h infback9.h inffix9.h zstream.h zfstream.h 


| 
l TDBC 
Language Tcl00 and C 
Primary Site http://core.tcl.tk/tdbc 
Contact: kennykb@acm. org, Kevin Kenny 


Tcl Revision Supported Tcl: 8.6 and newer 
Supported Platforms UNIX,MS Windows, MacOSX 


The tdbc package provides a single common interface to many different database engines. 
Connections to multiple database engines can be open at once. 

The tdbc package requires a driver to map from a specific database engine’s command set to the 
tdbc commands. Drivers are provided for Oracle, Postgres, Mysql, and Sqlite3. A wide variety of 
database engines are supported via the generic ODBC driver. New drivers can be written in pure Tcl 
(using TclOO) or as compiled extensions. 

The tdbc package is part of the standard distribution, but the base tdbc package and drivers are 
not automatically loaded into a Tcl application. An application must require the tdbc driver packages 
it will need. The base tdbc package will be loaded automatically. Using package require to load 
both the base tdbc and tdbc: : driver packages is not an error. 


en 
Example 7 
Script Example 

it Load the base tdbc 

package require tdbc 
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i## Load sqlite3 support 
package require tdbc::sqlite3 


if Load mysql support 
package require tdbc::mysql 


After the driver has been loaded an application can create a connection to the database engine or 
engines. Each time you create a connection to a database engine a new command is created to interact 
with that database engine. The new command can be used to select specific databases within the engine 
and perform SQL operations on those databases. 


The tdbc: : connection command creates a connection to the database engine. 


Syntax: tdbc::driver::connection create dbCmd ?-option value? 


Open a connection to a database engine. 


driver The driver for this database engine — sqlite3, mysql, etc. 


dbCmd_ The name of the new command to use to interact with this 


database. 


The options supported for the tdbc: : connection command vary depending on the requirements 
of the underlying engine. All of the drivers support these options: 


-readonly boolean Ifthe boolean argument is true, the database cannot be 


-timeout ms 


modified. The default is false, to allow a database to be 
modified by the script. 

A timeout value in milliseconds. The default value is 0 
which will wait forever. 


Options that are related to specific drivers include: 


Sqlite. 
fileName 
MySal, Oracle. 
-host addr 


-port portNum 
-socket path 
-db name 


-user name 
-passwd pwd 


The name of the sqlite database file. 


The address of the host running the database 
server. 


The port number at which the database server is 
accepting connections. 


The path to a Unix socket or named pipe if the 
server and application are running on the same 
host. 


The database to attach. 
The login for this database. 


The password for this user and database. 
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ODBC. 


connectionString A db-server specific set of connection values. 
Check the documentation for the database 
engine’s ODBC driver for the format of this 
string. 


One driving principle of tdbc was to make it easier to write safe code than unsafe code. Most 
database applications are vulnerable to injection attacks or other issues from malformed data. The code 
to prevent attacks and sterilize inputs can be cumbersome and may need to be repeated throughout an 
application. 

tdbc provides a mechanism for creating an SQL command with references to data and then allow- 
ing the tdbc driver to substitute the actual values into the final SQL INSERT or SELECT commands. 
During the substitution phase all inputs and returns are sterilized and escaped safely and properly. 

Values are referenced using a bound variable. A bound variable is defined within an SQL command 
by starting the variable with a single colon. When this command is evaluated, the bound variable is 
replaced with the contents of a Tcl variable with the same name. 


aaa 
Example 8 
Script Example 

set data "This needs cleanin’" 

set sql "INSERT INTO atable VALUES (:data)" 


An SQL command can be evaluated directly, but the preferred method is to use the connection’s 
prepare subcommand to perform substitutions and sterilize the inputs. The prepare subcommand 
accepts an SQL statement and creates a new command (actually a TclOO object) which can be used 
to evaluate the command later. Any number of statements can be prepared and retained until they are 
needed. 


Syntax: dbCmd prepare statement 
Prepare an SQL statement for later evaluation. 


statement A valid SQL command. This statement may 
include bound variables. 


eee 
Example 9 


Script Example 
if An SQL statement can include all data: 


set insert [dbCmd prepare { 
INSERT INTO author (firstname, lastname) 
VALUES (*Clif’, ‘Flynt’ )}] 


i## The prefered technique is to use bound variables: 
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set insert [dbCmd prepare { 
INSERT INTO author (firstname, lastname) 
VALUES (:first, :last)}] 

set first "Clif" 

set last "Flynt" 


A prepared command can be evaluated with the statement’s execute subcommand. The execute 
subcommand can map bound variables using a provided dict or from existing Tcl variables. 


Syntax: statementCmd execute ?dict? 
Evaluate a prepared SQL statement. 


statementCmd The command created by a dbCmd prepare 
command. 


dict A dictionary in which dictionary keys match the 
names of bound variables. If this is provided, the 
bound variables will be mapped to the dictionary 
values. If it is not provided bound variables will be 
mapped to local variables. 


_—_— $e 
Example 10 
Script Example 
set insert [dbCmd prepare { 
INSERT INTO author (firstname, lastname) 
VALUES (:first, :last)}] 


if Add Clif Flynt to author table 
$insert execute [dict create first Clif last Flynt] 


if Add Mark Twain to author table 
set first Mar 
set last Twai 
$insert execute 


Depending on the application and data sizes it can be simpler to retrieve all the results of a SELECT 
command at once, or to iterate through the returns one at a time. The statementCmd has two subcom- 
mands to support this. The al] rows subcommand returns all the results as a single dict or list. The 
foreach subcommand defines a loop for processing results in a row-by-row manner. 


Syntax: statementCmd allrows ?-option value? ?dict? 
Execute a statement and return all results. 
-as value Defines whether the return should be as a list 
or a dict. The value must be one of 1 ists or 


dicts. The default is to return the data as a 
dict. 
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-columnsvariable varName If this option is included the list of column 
names will be placed into the named variable 
in the order that the data appears in the return. 
This is useful when data is returned as lists. 


dict A dictionary to use when mapping bound 
variables to values. 


eee ee eee 
Example 11 
Script Example 


set data [$get allrows —as lists —columnsvar colNames ] 


foreach rtn $data { 
foreach val $rtn name $colNames { 
puts "$name: $val" 


} 


Script Output 
id: 1 
firstname: Clif 
lastname: Flynt 
id: 2 
firstname: Mark 
lastname: Twain 


If your application will be processing the results in a loop, the foreach command may be more 
appropriate. 


Syntax: statementCmd foreach ?-option value? ?dict? varName script 


Execute a statement and iterate through the returned rows in a script. The script is 
evaluated once for each row. 


-as value Defines whether the return should be as a list or a 
dict. The value must be one of 1ists or dicts. 
The default is to return the data as a dict. 


-columnsvariable name _ If this option is included the list of column names 
will be placed into the named variable in the 
order that the data appears in the return. This is 
useful when data is returned as lists. 


dict An optional dictionary to use when mapping 
bound variables to values. 

varName The name of the variable to contain the returned 
row while iterating through the list. 


script A script to evaluate once for each row of data 
returned. 
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_.——_AA 
Example 12 
Script Example 

set report [LdbCmd prepare {SELECT * FROM author} ] 

$report foreach -as dicts author { 


puts $author 
} 


Script Output 
id 1 firstname Clif lastname Flynt 
id 2 firstname Mark lastname Twain 


The next example uses these commands to create a library database with books and authors. 
Note that the single quote in this book’s title and the embedded SELECT command in the bookInsert 
statement work correctly, while Nasty Hacker’s attempt at confusing the database with an injection 
attack fails. 


OOo —-—n—n— Oe wy »z= 
Example 13 


Script Example 


i#fpackage require tdbc 
package require tdbc::sqlite3 


jf Remove the database if it already exists. 
catch {file delete bookfile.sql} 


i## Open a sqlite database named bookfile.sql 
if The new command for this conenction is dbCmd 


:tdbc::sqlite3::connection create dbCmd bookfile.sql 


i## The database is empty, 
if Use the allrows command to create tables. 


dbCmd allrows {CREATE TABLE book ( 

id INTEGER PRIMARY KEY AUTOINCREMENT, 
authorid INT REFERENCES author, 

title VARCHAR(50) )} 


dbCmd allrows {CREATE TABLE author ( 

id INTEGER PRIMARY KEY AUTOINCREMENT, 
firstname VARCHAR(20), 

astname VARCHAR(20) )} 


if Insert a row into the author table. 


set insert [dbCmd prepare { 
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INSERT INTO author (firstname, lastname) VALUES (’Clif’, ’Flynt’)}] 


$insert execute 
## Multiple entries are simpler using bound variables :fn, :1n 


set insert [dbCmd prepare { 
INSERT INTO author (firstname, lastname) VALUES (:fn, :1n)}] 


foreach {fn In} {John Ousterhout Brent Welch Mark Twain Nasty Hacker} 


$insert execute 
} 


if A bound variable can be used within an embedded SELECT 


set bookInsert [dbCmd prepare { 
INSERT INTO book (authorid, title) VALUES 
((SELECT id FROM author WHERE firstname = :first), :title)}] 


set authorTitleList { 
Clif "Tcl/TK: A Developer’s Guide" 
Brent "Practical Programming in Tcl/Tk" 
Mar "Tom Sawyer" 
Mar "Huckleberry Finn" 
Nasty "(SELECT firstname FROM author limit 1)" 
John “Tcl and the Tk Toolkit" 
} 
foreach {first title} $authorTitleList { 
$bookInsert execute 


set report [dbCmd prepare {SELECT * FROM book} ] 
set getAuthor [dbCmd prepare \ 
{SELECT firstname, lastname FROM author WHERE id=:authorid}] 


$report foreach -as lists bookList { 
lassign $bookList id authorid title 
set author {x}[$getAuthor allrows -as lists] 
puts “$author" 
puts " $title\n" 
} 


Script Output 
Clif Flynt 
Tcl/TK: A Developer’s Guide 


Brent Welch 
Practical Programming in Tcl/Tk 


Mark Twain 
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Tom Sawyer 


Mark Twain 
Huckleberry Finn 


Nasty Hacker 
(SELECT firstname FROM author limit 1) 


John Ousterhout 
Tcl and the Tk Toolkit 


= 
17.5 Rivet 
Language Tcl and C 
Primary Site http://tcl.apache.org/rivet/ 
Mailing List rivet-dev-subscribe@tcl.apache.org 
Original Authors: David Welton, Damon Courtney, Karl Lehenbauer 
Contact: mxmanghi@apache.org, Massimo Manghi 


Tcl Revision Supported Tcl: 8.4 and newer 


Supported Platforms UNIX, MacOSX 

There are many tools available for generating web pages dynamically with Tcl. These range from 
the simple CGI techniques that the Web started with to full HTTP servers like tcl httpd, Wub and 
AOLServer. 

Rivet is an Apache plugin that allows you to embed Tcl into an HTML page or generate a complete 
page dynamically. It has support for creating and processing forms, works with Ajax, XML-based 
applications, JQuery and other Web 2.0 Technologies as well as with traditional HTML. 

This industrial-strength package is in use at many public and commercial sites. It is included with 
the SuSE, Redhat, Centos, Debian and Ubuntu distributions. 

The simple way to use Rivet is to install mod_rivet in your Apache directory (probably /usr/ 
lib/apache2/modules). If you use an RPM or apt package this will happen automatically. If you 
build from source, the make instal] will perform this. After installing Rivet, it must be enabled by 
adding the following lines to the Apache configuration file (probably httpd.conf on SuSE or RedHat 
installations or apache2.conf on Debian or Ubuntu installations). 
httpd.conf 

LoadModule rivet.module /usr/lib/apache2/modules/mod_rivet.so 

AddType application/x—httpd—-rivet rvt 

AddType application/x-rivet—tcl tcl 

AddType "“application/x—httpd—-rivet; charset=utf—8" rvt 


If you have the Apache mod_dir installed you can use an index.rvt file instead of index.html 
as the default file to load when a browser requests a folder. This is defined by adding a line like the 
following to the httpd.conf file. 
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httpd.conf 


DirectoryIndex index.rvt index.html 


You will need to restart your Apache server after these changes. 

You can add Tcl code to an HTML page by naming the page with a .rvt suffix and enclosing the 
Tcl code within a pair of angle bracket-question mark pairs. New text is added to the web page with 
the puts command as shown below. 


rere 
Example 14 
Simple Rivet Example 
<html> 
<body> 
<H1l> NOW: 
<? puts [clock format [clock seconds] -format \%H:\%M] ?> 
</H1> 
</body> 
</html> 


A page can be a mixture of HTML and Tel scripts, as shown above, or completely generated by Tcl 
scripts. 
The htm] command encloses a string with one or more HTML tags. 


Syntax: html string tagl tag2 ... 
Returns a string with opening and closing tags around it. 


string String to display in the HTML output. 

tagl, tag2 ... ‘Tags to put around the string. The first tag will 
be the outermost tag and the last will be the 
innermost. 


The previous page can also be written as: 


DB 


Example 15 
Script Example 
<? 
html \ 
"NOW: Lclock format [clock seconds] —format %H:%M] \ 
html body hl 
?> 


Rivet includes several configuration options that can be set in the httpd.conf file. These options 
support setting scripts to be run before and after a page is loaded, when Apache starts or ends a process, 
how to allocate resources and more. Check the current Rivet documentation under directives for 
more details on these. 
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Configuring Rivet to automatically run scripts when a new process is created or a new page is 
loaded is a powerful way to localize code that defines the way a website performs. This makes a site 
simpler to maintain than having duplicated text in each web page. 

These features are enabled by adding RivetServerConf lines to the httpd.conf file. The 
ChildInitScript will be evaluated when apache starts a new process. The BeforeScript will 
be evaluated before each page is loaded. The next example defines a script perProcess.tcl to be 
sourced when a new Apache process is created, and perPage.tcl to be sourced when each .rvt 
page is loaded. The following configuration will evaluate the perPage.tcl script when pages with a 
.rvt or .tcl suffix are loaded, but not when plain . htm] pages are accessed. 


httpd.conf with Tcl Initialization Scripts 
LoadModule rivet_module /usr/lib/apache2/modules/mod_rivet.so 
AddType application/x—httpd—-rivet rvt 
AddType application/x—rivet—tcl eG] 
AddType “application/x—httpd—rivet; charset=utf—8" rvt 


RivetServerConf ChildInitScript “source /var/www/lib/perProcess.tcl" 
RivetServerConf BeforeScript "source /var/www/lib/perPage.tcl" 


The ChildInitScript script is only guaranteed to be evaluated when Apache starts. The 
BeforeScript is evaluated for each page. It’s simpler to develop special code in a BeforeScript, 
and then move the debugged code to a Chil dInitScript when it’s stable. 

It’s best to do persistent setup like creating common procedures in a ChildInitScript file. This 
reduces the overhead of creating the procdures when each page needs them. 


perProcess.tcl 
proc time {} { 
return [clock format [clock seconds] -format "%H:%4M" ] 


The next example show how the perPage.tc] file can use the time procedure to insert boilerplate 
text into each page. 


OOOO nnn — ay >= 
Example 16 
perPage.tcl 

puts "<hl>Now: [time]</hl>" 


With these definitions and files, all . rvt pages will display Now: 12:34 at the top of the page. 

Rivet includes many commands to make it easier to generate web pages including generating forms, 
tracking cookies and session management. 

Rivet’s form support is handled in an object-oriented manner, similar to Tk objects. A web page 
can have multiple forms, and each form is connected to a unique set of data and has a unique command 
name. Once a form object is created, text entries, labels, radiobuttons, etc. can be added to it. 
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Syntax: form formName ?-OPTION? ?VALUE? 
Create a form object to be populated and displayed. 


formName The name of this form. A new command with this name will be 
created. 


The form command supports several options, including: 


-method Selects the submission method for this form the VALUE may be 
post or get. The default is post. 

-name Sets the name to be used in the HTML forms <form 
name="VALUE"> tag. 

-action Defines the URL to receive the data when the submit button is 
clicked. If this is blank, the URL of the page generating the 
form is used. 


————— 
Example 17 
Rivet Create form Example 

form tstForm —method get —name test 


Once a form object is created, it needs to be placed in the HTML page and populated with the form 
elements. 

The start command inserts the form tag into your document. This must be placed after the form 
is created and before elements are created, but is not otherwise constrained. 


:3_—_—_- ANNONA 
Example 18 
Rivet form Start Example 

form tstForm —method get —name test 

html "Fill in this form" h2 

tstForm start 


Creating form elements follows a pattern: 
formName elementType name ?-option value 
formName The name of the form to associate this 
element with. 


elementType The type of the element. May be one of 


text, radiobutton, checkbutton, 
select, submit, etc. 


name The name associated with this element. This 
name is linked to the user-provided value 
when the form is submitted. 
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?-option value Whatever options and values are appropriate 
to the element being added. The option/- 
value pair will be added to the HTML as 
option="value". 

form tstForm —method get —name test 
tstForm start 


if Prompt for a name 
html "Enter your name: " b 
tstForm text name —size 20 


dt Add a hidden field 
tstForm hidden displayed —value 1 


if Add the submit button 
tstForm submit submit —value "Submit" 


The final step in creating a form is to end it. 

The end command adds the </form> tag to complete the form. 
form tstForm —method get —name test 

tstForm start 


html "Enter your name: " b 
tstForm text name —size 20 


tstForm submit submit —value "Submit" 


tstForm end 


Once a form is submitted, a page needs to process it. The var command returns information about 
variables submitted with a form. This command supports several subcommands. 


Syntax: var exists varName 
Returns true if the named variable exists in the post (or get) data. 


varName The name of the variable, as defined in the 
form element. 


i## displayed is a hidden variable that exists 
i## if this page has been displayed already. 
if {Lvar exists displayed]} { 


} 


Syntax: var get varName 
Returns the value associated with the named variable. 


varName The name of the variable, as defined in the form element. 
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## Check the required input 


if {!Lvar exists name] 
(Lvar get name] eq "")} { 
set fail 1 


Syntax: var al] 
Returns the variables as a varname/value list, suitable for using with array 
set or the dict commands. 


array set values [var all] 


The next example creates a form requesting three pieces of information. When the user clicks 
Submit, the page is called again. The second time the page is loaded, the form variables have been 
populated. 

The code that creates the form is placed at the end of the page definition. This allows the script 
to check for valid data before generating any display output. If the inputs are not complete, the form 
processing is aborted and control passes down to the form display section. If the inputs are complete, 
the values can be processed and the user can be redirected to a new page or a new set of html can be 
displayed. 

If the inputs are complete this example displays a message and cancels the form display with the 
return command. The page could also redirect the user to a new page once the processing is complete. 


ooo —_.—n—n— aay»: = 
Example 19 


Script Example 
<? 
package require form 


## displayed is a hidden variable that exists 
it if this page has been displayed already. 
if {L[var exists displayed]} { 


## If displayed exists, check the values. 
## Assume OK 
set ok 1 


## Check the required inputs. 
## Generate a prompt if a field is missing. 


foreach required {name quest language} { 
if {!€var exists $required] 
(Lvar get $required] eq "")} { 
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set ok 0 
html "Fill in $required" br 


} 


if If ok, check the answer and return 

d## else fall through and redisplay the form. 

if {$ok} { 
if Destroy tstForm object - we’re done with it. 
tstForm destroy 


if {Lvar get language] eq "Tcl"} { 
html "Good Answer" hl 
} else { 
html "Into the Gorge with ’im" hl 
} 
return 


} 
it Only get here if something fails or first time 
html "Form Demo" title 


it Create a form object 
## Earlier versions of Rivet used 
i## form create tstForm -method get -name test 


form tstForm -method get -name test 
## Start the output 
tstForm start 

it Add fields to the for 


foreach {prompt field size} { 
"What is your name?" name 15 
"What is your quest?" quest 25 
"What is your favorite language?" language 8 
bf 
if {[var exists $field]} { 
set val [var get $field] 
} else { 
set val "" 
} 
html $prompt b 


tstForm text $field -size $size -value $val 
html <br> 
} 


it Add the last hidden field and submit button 

i## then finish the form 

tstForm hidden displayed -value 1 

tstForm submit submit -value "Submit" 

tstForm end 

2> 

Script Output 

File Edit View Go Bookmarks Tools Settings 
&»v @ OO Gy 268.1.217/form mM a v 
Wie 


What is your name? 
What is your quest? 


What is your favorite language? 
Submit 


» fg 


»> 
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Web pages with static pages require frequent manual modifications when new material is added. 
The ChildInitScript and BeforeScript directives can be used to dynamically create pages. The 
dynamically created pages can be created from a database or by examining a folder. 

The next example shows how to build a set of scripts that will look in the current folder for files 
that end with quiz.tc1. The file names will be used to create a navigation bar list of selections. When 


a user has selected a quiz, that quiz will be displayed in the main window. 


To add a new quiz to the website, you simply copy the new fooquiz.tcl file to the folder with 
the other quizzes and it is automatically added to the list of quizzes to select from. 
The ChildInitScript has a single procedure that uses the glob and string commands to 


construct an HTML list of names with links to the appropriate quiz file. 


$$ 


Example 20 
ChildInitScript 
proc makeMenu {} { 
set rtn "<ul>\n" 
foreach f [glob —nocomplain *xquiz.tcl] { 


append rtn "<li> <a href=\"/clif/quizes.rvt?page=$f\"> 
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set fileName [file rootname [file tail $f]] 
append rtn “[Estring range $fileName 0 end—4]" 
append rtn "</a>\n" 

} 

append rtn “</ul>\n" 

return $rtn 


The BeforeScript generates the page content. It uses a small stylesheet to split the page into 
navbar and content windows. The page value is defined by the link in the makeMenu procedure. The 
contents of page file are the same as the previous form example, except that the opening <? and closing 
?> symbols are removed. 


=> A> A AN ss AAh9]9Rhp$ 
Example 21 
BeforeScript 
puts —nonewline { 
<html> 
<head> 
<title>} 
puts —nonewline Quizes 
puts {</title> 
<link rel="stylesheet" type="text/css" href="/clif/simple.css" > 
</head> 
} 
puts { <div id="navbar">} 
puts LmakeMenu ] 
puts " </div>" 
puts { <div id="content">} 


set page [var get page] 
if {$page ne ""} { 
source $page 
} else { 
puts "<h2>Select a quiz</h2>" 


} 
puts </div>" 
puts "</html>" 


simple.css 
#fnavbar { 
float: left; 
width: 90px; 


padding: 20px Opx 10px 10px; 
font-size: 18px; 
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#fcontent { 
width: 60em; 
margin: Opx Opx Opx 6em; 
padding: lem 2em; 
border—bottom: 1px solid #ccc; 


A larger, more complete example of using the ChildInitScript and BeforeScript directives is 
included on the companion website. 
When the quiz folder has two files timquiz.tcl and tclquiz.tcl the browser displays this: 


Before Selecting a Quiz 


My name is Tim - answer my questions 


truly or be cast into the gorge. 


What is your name? 

What is your quest? 

What is your favorite language? 
Submit 


Rivet provides support for tracking cookies. The cookie command has two subcommands to set 
or get the value of a cookie. 


Syntax: cookie set cookieName value ?-option value? 
Sets a cookie in the user’s browser. 
cookieName The name to associate with this cookie. 


value The value to associate with this cookie. 
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Several options are supported, including: 
-days dayCount A number of days until the cookie expires. 
-hours hourCount A number of hours until the cookie expires. 


-minutes minuteCount A number of minutes until the cookie 
expires. 


Retrieving a cookie is done with the cookie get command. 


Syntax: cookie get cookieName 
Returns the value associated with the named cookie, or an empty string if the cookie 
has not been set. 
cookieName The name defined for this cookie with the 
cookie set command. 


The Rivet package is in active development and use. It includes many more commands and pack- 
ages with more being added frequently. The HTML documentation package that comes with the 
distribution describes many other features. 


— 


7.6 BWidgets 
Language Tcl 
Primary Site http://sourceforge.net/projects/tcllib/ 


Tcl Revision Supported Tcl: 8.0-8.6 and newer; Tk: 8.0-8.6 and 
newer 


Supported Platforms UNIX, MS Windows, Macintosh 


Chapter 14 described how to create complex megawidgets from the simple Tk widgets. The BWid- 
gets package provides many of the commonly used megawidgets (such as tab notebooks and a tree 
display widget), and versions of standard Tk widgets with expanded features, including buttons and 
labels with pop-up help, resizeable frames, and more. 

The BWidgets package includes extensive documentation as HTML files. The following examples 
demonstrate using a few of the widgets and commands. 

A tabbed notebook has become a standard widget for GUI programs. It provides a good way to 
present different sets of related information to a user. The BWidgets package includes a NoteBook 
widget that can be configured to appear as you wish for your application. 


Syntax: NoteBook widgetName ?option value?... 
Create a tabbed notebook widget. 
widgetName The name for this widget, following normal Tk window 
naming rules. 
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option value A set of options and values to fine-tune the widget. The 
options include: 


-font fontDesc The font to use for the notebook 
tabs. 

-height height The height of the tab notebook. 

-width width The width of the tab notebook. 


-arcradius number Describes how round the corners of 
the tabs should be. 
A NoteBook widget supports many subcommands to manipulate it, including the following. 


Syntax: notebookName insert index id ?option value? 


Insert a new tab page into the notebook. This command returns a frame to hold the 
content for the new page. 


notebookName The name of a previously created tab NoteBook widget. 
index The location of the new tab. May be an integer or end. 
id An identifier for this page. 


option value A set of options and values to fine-tune the widget. The 
options include: 


-text text The text to display in the tab. 


-createcmd script A script to evaluate the first time 
the tab is raised. 


-raisecmd script A script to evaluate each time the 
tab is raised. 


Syntax: notebookName raise id 
Raise a notebook page to the top. 


notebookName The name of a previously created tab NoteBook widget. 


id An identifier for this page. 
OOOO nnn — Oy» =— 
Example 22 
Script Example 


package require BWidget 


set nb [NoteBook .nb -height 100 -width 250] 
grid $nb 
set pl [$nb insert end pagel -text "Page 1"] 
set p2 [$nb insert end page2 -text "Page 2"] 
label $pl.1 -text "Page 1 label" -bg ##ccc 

pack $pl.1 
$nb raise pagel 
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Script Output 


Page 1 | Page 2 | 


Page 1 label 


In any form type application you end up with many sets of labels and associated entry widgets. 
The LabelEntry widget provides a simple way of creating label and entry pairs with automatic help 
displays. 


Syntax: LabelEntry widgetName option value 
Create a label and entry pair. 
option value A set of options and values to fine-tune the widget. 
The options supported by the Tk label and entry 
widgets are supported, as well as the following. 


-label text The text to display in the label 
portion of this widget. 

-helptext text Text to display when the cursor rests 
on the label for a period of time. 


-font fontDesc Defines the font for the entry 
portion of this widget. This may 
be different from the font used by 
the label widget. 

-labelfont fontDesc Defines the font for the label 
portion of this widget. This may 
be different from the font used by 
the entry widget. 


oOo nnn — ay »»z= 
Example 23 


Script Example 
package require BWidget 


LabelEntry .le -font {arial 16} \ 
-labelfont {Times 18} \ 
-label "Name: " \ 
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-helptext "What is your name?" 
grid .le 


Script Output 


ame: |Clif Flyn{ 
a 


Another common need is a window with a scrollbar. The BWidget Scrol 1edWindow widget provides 
a window in which the scrollbar appears when the data exceeds the display area, and vanishes if there 
is no need for a scrollbar. 


Syntax: ScrolledWindow widgetName ?option value? 
Create a window that will hold a scrollable widget (canvas, text, or listbox 
widget) and display scrollbars when needed. 
widgetName The name for this widget, following normal Tk window 
naming rules. 
option value A set of options and values to fine-tune the widget. The 
options include: 


-auto type Specifies when to draw scrollbars. The type field 


may be: 

none Always draw scrollbars. 

horizontal Horizontal scrollbar is drawn as 
needed. 

vertical Vertical scrollbar is drawn as needed. 

both Both scrollbars are drawn as needed. 
This is the default. 


The setwidget subcommand will assign a widget to be the scrolled widget in a ScrolledWindow 
megawidget. 
Syntax: widgetName setwidget subWindowName 
Assign subWindowName as the scrolled window in the widgetName 
ScrolledWindow widget. 
widgetName The name for the Scrol1edWindow widget, following 
normal Tk window naming rules. 


subWindowName The name for the window to be scrolled. This window must 


be achild of widgetName. 
ee 
Example 24 
Script Example 


package require BWidget 


if Create the ScrolledWindow 
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set sw [ScrolledWindow .sw] 


it Grid it and configure sw to change 
if when the main window resizes. 


grid .sw -sticky news -row 1 -column 1 
grid rowconfigure . 1 -weight 1 
grid columnconfigure . 1 -weight 1 


if Create a child to be held in the window 
canvas $sw.cvs -height 60 -width 80 -background #ddd 


i## Map the child into the ScrolledWindow 
sw setwidget $sw.cvs 


i## Put some graphics into the canvas 
sw.cvs create rectangle 3 3 40 40 -fill black 
sw.cvs create oval 40 40 80 80 -fill gray50 


if Define the scrollregion to cover everything drawn. 
sw.cvs configure -scrollregion [$sw.cvs bbox all] 
Initial 


, Shrink Width and Height 


Using the BWidgets, a GUI for a modern library with books, music and videos might look like 
this: 


Script Output 


Example 25 


Script Example 
package require BWidget 


set nb [NoteBook .nb -height 100 -width 300] 
grid $nb 


set pl 
set p2 
set p3 


LabelEnt 
-tex 
LabelEnt 
-tex 
LabelEnt 
-tex 


button 


grid 
grid 
grid 
grid 


he “SS ey 


LabelEnt 
-tex 
LabelEnt 
-tex 
LabelEnt 
-tex 


button 


grid $p2 
grid $p2 
grid $p2 
grid $p2 


proc boo 
global 
set to 
set no 
set le 
foreac 
tf 


append notice "$leader [string totitle $in] = $book($in)\n" 
set 


} 
label 


[$nb insert end book -text "Book"] 
[$nb insert end music -text "Music"] 
[$nb insert end video -text "Video"] 


ry $pl.title -label “Title: my 
tvariable book(title) -width 25 

ry $pl.author -label "Author: " \ 
tvariable book(author) -width 25 

ry $pl.subject -label "Subject:" \ 
tvariable book(subject) -width 25 


pl.search -text "Search" -command bookSearch 


title 
author 
subject 
search 


ry $p2.title -label "Title: " \ 
tvariable music(title) -width 25 
ry $p2.artist -label "Artist:" \ 
tvariable music(artist) -width 25 
ry $p2.genre -label "Genre:" \ 
tvariable music(genre) -width 25 


p2.search -text "Search" -command musicSearch 


title 
artist 
.genre 
search 


Search {} { 

book 

p [toplevel .t] 

tice "Searching for book with\n" 
ader "" 

h in [array names book] { 
book($in) ne ""} { 


leader "and" 


top.1] -text $notice -bg gray -borderwidth 3 \ 


-relief raised 


grid $ 


top. | 
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Script Output 
Book Tab Toplevel Search window 
Book | Music | Video | 


Title: /Tcl/Tk: A Developer's Guide 


Author: | Clif Flynt} 


Subject: Searching for book with 


Title = Tcl/Tk: A Developer's Guide 


Search | and Author = Clif Flynt 


17.7 GRAPHICS EXTENSIONS: Img 


Language G 
Primary Site http://sourceforge.net/projects/tkimg/ 
Contact Jan. Nijtmans@wxs.n1, Jan Nijtmans 
Tcl Revision Supported Tcl: 7.6p2-8.6 and newer; Tk: 4.2p2-8.6 
and newer 


Supported Platforms UNIX, MS Windows 


The Img extension adds support for BMP, XBM, XPM, GIF (with transparency), PNG, JPEG, TIFF, 
and postscript images to the Tk image object (described in Chapter 10). You must have the Jibtiff, 
libpng, and libjpg libraries available on your system to read TIFF, PNG, or JPEG image files. These 
libraries are all public domain and easily acquired from the Sourceforge tkimg site, or from these 
sites. 


e TIFF library code: ftp://ftp.sgi.com/graphics/tiff/ 
e PNG library code: ftp://ftp.uu.net/graphics/png 
e JPEG library code: ftp://ftp.uu.net/graphics/jpeg 


17.8 BOTTOM LINE 


e There are many extensions to enhance the base Tcl/Tk functionality. 
e Not all extensions are available for all platforms and all Tcl revisions. 
e Tcl extensions tend to lag behind the core Tcl releases. 
e The primary archive for Tcl code is core.tcl. tk. 
e Extensions are frequently announced in comp.lang.tcl or 

comp. lang.tcl.announce. 
e Many frequently used extensions are mentioned in the FAQ. 


CHAPTER 


Programming Tools 


One of the tricks to getting your job done efficiently is having the right tools for the job. There are 
plenty of tools available for developing Tcl applications. 

This chapter provides a quick description of several program development tools that are in use in 
the Tcl community. It is not a complete listing of tools. If the tool you need is not mentioned here, try 
checking the Tcl Resource Center at www.tcl.tk/resource/, the announcements in comp. 1ang.tcl, the 
FAQs at www. purl.org/NET/Tcl- FAQ, or the Tcler’s Wiki http://wiki.tcl.tk/. 

Development tools for Tcl are rapidly changing and improving. This chapter discusses the versions 
of the tools that were available in August 2011. New versions of many of these packages will be 
available before the book and companion website are published. 

The Open Source community is generating new ideas and packages, and commercial developers 
such as ActiveState, Neatware, and others have released full-featured toolkits that are constantly being 
improved. These options provide the Tcl developer with tools that can be configured to your needs and 
high-quality, commercially supported tools. 

General purpose tools like vim and emacs have smart modes for editing Tcl files. 
The Eclipse (http://blogsai.wordpress.com/2009/10/15/configuring-eclipse-as- 
tcltk-ide/) and NetBeans (http: //netbeans.org) IDE also have Tcl/Tk plugins. 

Neatware (www.neatware.com/) and ActiveState (www.activestate.com) have each taken portions 
of the TclPro suite and enhanced them for new commercial products. Neatware has developed a Tcl- 
oriented IDE that includes a context-sensitive editor, debugger, code checker, byte-code compiler, and 
more. ActiveState has enhanced the Tcl Pro suite of tools and renamed it Tcl Dev Kit. The Tcl Dev Kit 
extends the TclPro suite by 


¢ providing support for 


Tcl 8.6 TkTable BWidgets Tk 8.6 
Tellib TclLXML TclX TcIDOM 
TcISOAP [incr Tcl] {incr Tk] Img 
IWidgets Snack TkHTML TkCon 
Tcom Expect TclOO TDBC 


e adding GUI front ends to the TclPro compiler and wrapper 
e providing code coverage and hot spot profiling support in the debugger 
e providing binaries for Linux, HP-UX, Solaris, and MS Windows 


Tel/Tk: A Developer’s Guide. DOI: 10.1016/B978-0-12-384717-1.00018-X 703 
© 2012 Elsevier, Inc. All rights reserved. 
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The Tcl Dev Kit is designed to work with the commercial product Komodo Integrated Develop- 
ment Environment. ActiveState also supports the Komodo Editor, a free context-sensitive editor which 
supports Tcl, Perl, Python, Ruby, C, C++, HTML, and many other languages. 

The complete Komodo Integrated Development Environment includes real-time syntax checking, 
GUI debugger, packaging and distribution tools, support for large projects, support for Tcl/Tk, Perl/Tk, 
Python/Tk, XML, HTML and JQuery, a regular expression wizard, and more. 


This chapter briefly covers the following free and commercial tools. 


Code Formatters 


frink Reformats code into a standard style for easy comprehension. 


Code checkers 
tclCheck Checks for balanced brackets, braces, and parentheses. 


nagelfar Checks for syntax errors, unset or nonexistent variables, incor- 
rect procedure calls, and more. 


Debuggers 
Don Libes’s This is a text-oriented package with support for setting break- 
Debugger points, examining data, and so on. 


Packaging Tools 


FreeWrap Wraps a tclsh or wish interpreter with your application for 
distribution. 
Starkit Starkit wraps the entire Tcl/Tk distribution into a single file with 


hooks to evaluate scripted documents. This provides a middle 
ground between a fully wrapped and fully scripted package. 
Exercising and Regression Testing 


TkTest Records GUI events and internal state as an application is run 
and then replays the events and checks that the internal state 
matches the previous state. 


Tcl Extension Generators 


swig swig creates Tcl extensions from libraries of C functions by 
reading the function and data from an include file. 


Crifcl CriTcl generates a loadable Tcl extension from C code 
embedded into a Tcl script. 

Integrated Development Environments 

Komodo The Komodo IDE supports Tcl and other languages on UNIX 
and Windows platforms. 

My rmecox The MyrmecoX IDE is optimized for Windows platform and 
supports several packages. 
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18.1 CODE FORMATTER 


18.1.1 frink 

Despite our best efforts, after several hours of refining our understanding of the problem (i.e., hacking 
code), we usually end up with badly formatted code. Incorrectly formatted code makes the logic diffi- 
cult to follow and hides logical or syntax errors caused by misplaced braces. Reformatting the code can 
frequently help you find those errors. The frink program will reformat a Tcl script to make it more 
comprehensible and can check syntax. 


Language C 
Primary Site Stp://catless.ncl.ac.uk/pub/frink. tar. gz 
Contact Lindsay.Marshall @ newcastle.ac.uk 


Tcl Revision Supported Tcl: 7.3-8.6 and newer; Tk: 3.6-8.6 and newer 
Supported Platforms UNIX, MS Windows, Mac 
Frink will convert your script to a format that closely resembles the recommended style for Tcl scripts 
described in the Tcl Style Guide. As added benefits, frink will check the script for syntactic errors 


while it is reformatting the scripts, and the reformatted script will run faster. Frink supports several 
command line options to define how the code will be formatted. 


-a put spaces around -command code in {} and “”’. (default = OFF) 
-A turns OFF processing of expr calls. 

-b add braces (see manual page for details) (default = OFF) 

-B turns OFF processing of code with bind calls. 


-c <n>_ set further indent for continuations to n. default = 2 
-C <f> generate proc specs for use by frink. default = OFF 


-d remove braces in certain (safe) circumstances (default = OFF) 
“D warn about dynamic names. default = OFF 

-e produce “else”. (default = OFF) 

=e. extract constant strings. The parameter is the locale for which the 


strings are currently written. If the -f flag is also used then only 
the constant strings that are rewritten will be output. Output goes 
to a file called <locale>.msg. (default = OFF) 


“Tf, rewrite strings for msgcat (default = OFF) 


-F selectively control heuristics. Currently the parameter is a single 
hex coded number with each bit representing a test. The values 
you need to know are: 


00001 var parameter testing 
00002 parameter number testing 
00004 parameter value testing 
00008 regexp parameter testing 
00010 return checks 
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00020 check for: or ::: in names 
00040 expr checks 
00080 foreach var checking 
00100 = check for omitted parameters 
00200 check switches on commands 
00400 check for abbreviated options 
00800 check for unusedness 
01000 = check for bad name choice 
02000 check for array usage 
04000 check for possible name errors 
2g indent switch cases (default = OFF) 
-G generate compiler style error messages (default = OFF) 
=h print this message 
-H turn on all heuristic tests and warnings (default = OFF) 


-i <n> _ set indent for each level to n (default = 4) 


-I treate elseif and else the same way (default = OFF) 
ee remove non-essential blank lines (default = OFF) 
-J just do checks, no output (default = OFF) 

-k remove non-essential braces 


-K <f> — specify file of extra code specs 

=| try for one-liners (not yet implemented) 

: minimize the code by removing redundant spacing (default = 
OFF) 

warn if there is no — on a switch statement (default = OFF) 

-n do not generate tab characters (default = OFF) 


: do not put a newline out before elseif (default = OFF) 
-0 obfuscate (not implemented yet) : default = OFF 
-Q <t> don’t format lines starting with token “t” 


-p <v> if v is a number produce that many blank lines after each 
proc definition, otherwise produce whatever format the code 
indicates. No codes are defined yet..... (default = do nothing) 


-P turn off processing of “time” command (default = OFF) 

=q put spaces round conditions (default = OFF) 

-Q warn about unquoted constants - not fully operational (default = 
OFF) 


- remove comments (default = OFF) 
-S <c> format according to style “c:” 
5 don’t preserve end of line comments (default = OFF) 
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t <n> set tabstops every n characters (default = 8) 
T produce “then” (default = OFF) 
u safe to remove brackets from elseif conds 
U hardline checking enabled (default = OFF) 
Vv put round variable names where appropriate 
Vv the current version number 
-w <n> _ set line length (default = 80) 
W halt on Warnings as well as errors 
x produce “xf style” continuations 
X recognize tclX constructs 
y don’t process -command code (default = OFF) 
¥ try to process dynamic code (default = OFF) 
Zz put a single space before the character on continuations 


=f control heuristics that are tested (-H turns on ALL tests) 
Frink is distributed as source code with a configure file for Posix-style systems. You can 
compile and link this program under Microsoft Visual C++ with the following procedure. 


1. Get a copy of Gnu getopt.c and getopt.h. (I found a good copy in the Gnu C library and as 
part of the Gnu m4 distribution.) 

. Copy getopt.c and getopt.h to the frink source code directory. 

. Within Visual C++ create a Win32 Console Application ( File/New/Projects). 

. Add the files ( Project/Add To Project/Files). 

. Build all. 


oR WD 


The following example shows frink being used to reformat a poorly formatted piece of code. 


$$ SS a 
Example 1 
Badly Formatted Script 
proc checksum \ 
{ 
txt 
} \ 
{ 
set sum 0; foreach 1 Esplit $txt ""] \ 
{ 
binary scan $1 c val 
set sum [expr {($sum>>1)+($sum*$val)}] 
lee return $sum 
} 


set data "12345678901234567890123456789012345678901234567890" 
puts [time {checksum $data} 100] 


708 CHAPTER 18 Programming Tools 


After frink 
proc checksum {txt} { 
set sum 0 
foreach 1 [split $txt ""] { 
binary scan $1 c val 


set sum [expr {($sum>>1) +($sum*$val)}] 
} 


return $sum 


set data "12345678901234567890123456789012345678901234567890" 
puts [time {checksum $data} 100] 


The frink program can also perform syntax checking. You can enable various tests with the -F 


flag, and add more command syntax definitions with the - kK flag. The format for a syntax definition is 
as follows. 


Syntax: cmdName { argl ...argN } 
cmdName The name of the command. 


argx An argument definition. May be one of: 
var Argument is the name of a variable. 
any Argument may be any value. 


args Any number of arguments. This value can only be the 
last element in the argument list. 


The following example shows frink being used to examine a buggy code fragment. 


FE 


Example 2 
badcode.tcl 


i## The next line is missing a closing quote 
proc foo {a b} {puts "a $b} 


if The next line has too few arguments 
foo b 


syntaxdef 
foo {any any} 


frink command 
frink -K syntaxdef badcode.tcl 


Output 


i## The next line is missing a closing quote 


xxx /tmp/badcode.tcl Warning : Missing " in proc foo (line 2) 
proc foo {a b} f{ 
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puts "a $b" 
} 


# The next line has too few arguments 
xxx /tmp/badcode.tcl Warning : Call of foo with too few parameters (line 5) 
foo b 


18.2 CODE CHECKERS 


One drawback of interpreted languages, as opposed to compiled languages, is that a program can run 
for months without evaluating a line of code that has a syntax error. This situation is most likely to 
occur in exception-handling code, since that is the code least often exercised. A syntax error in this 
code can cause your program to do something catastrophic while attempting to recover from a minor 
problem. 

There are several code checkers that will examine your script for syntax errors, and more are being 
developed. Although none of these is perfect (Tcl has too many ways to confuse such programs), these 
will catch many bugs before you run your code. 


18.2.1 tclCheck 


Language C 
Primary Site http://catless.ncl.ac.uk/Programs/tclCheck/ 
Contact Lindsay.Marshall @ newcastle.ac.uk 


Tcl Revision Supported Tcl: 7.3-8.6 and newer;Tk: 3.6-8.6 and newer 
Supported Platforms UNIX 


This program checks for matching parentheses, braces, and brackets and a few other common pro- 
gramming errors. Most Tcl syntax errors are caused by these easy to catch errors (or syntax problems 
that are identified by frink). TclCheck and frink can save you hours of time you would otherwise 
spend staring at your code and counting braces. 

TclCheck supports several command line flags to fine-tune its behavior. These include the 
following. 

-c By default tclCheck attempts to recognize comments so as to permit unmatching 
brackets in them. This flag turns this behavior off. 


-e This flag enables checking for lines that have a \ followed by spaces or tabs at their end. 
By default, this test is not carried out. 

-g By default, tcl Check pops its stack of brackets to a find a match with} > ] > ). This 
flag turns this off. 

-j This flag stops the printing of error messages beginning “Inside a string”. 

-j Generates a compressed skeleton printout where indentation is ignored when matching 
brackets (see —1). 
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-] Generates a compressed skeleton printout where nested matching lines are paired up and 
removed. Matching includes any indentation. 


-m Removes from the skeleton printout bracket pairs that match up directly on lines. 
-q Do not generate any output unless exceptions are detected. 
-S Generate a printout of the bracket skeleton of the entire program. 


-t Tiger mode. This will flag any single that occurs in places where Tcl would not detect the 
start of a string. By default this is turned off, but it can be very useful for tracking down 
some problems that are difficult to find. 

TclCheck is distributed as C source code with a Makefile. Like frink, it will compile under 
Windows if you get a copy of Gnu getopt.c to link with it. 


oe 
Example 3 
Script Example 

i## The next line is missing a closing quote 

proc foo {a b} {puts "a $b} 

if The next line has too few arguments 

foo b 


Script Output 
File ../buggy.tcl: 
Inside a string: unmatched } on line 3 char 27 
"missing, opened on line 3 char 22 
} missing, opened on line 3 char 16 


959 


18.2.2 nagelfar 


Language Tcl 
Primary Site http://nagelfar.berlios.de/ 
Contact peter.spjuth@ gmail.com 


Tcl Revision Supported Tcl: 8.4-8.6 and newer;Tk: 8.4-8.6 and newer 
Supported Platforms UNIX, Windows, Mac OS/X 


Nagelfar does a deep examination of a Tcl script and reports coding errors including mis- 
matched braces, parentheses, quotes, incorrect argument counts, undefined commands. It also provides 
some code coverage analysis. It can be extended to understand new commands (your own library of 
procedures) and can provide varying levels of reports. 


-help Show usage. 
-gui Start with GUI even when files are specified. 
-s <dbfile> Include a database file. (More than one is allowed.) 


-encoding <enc> Read script with this encoding. 
-filter <p> Any message that matches the glob pattern is suppressed. 


18.2 Code Checkers 711 


-severity <level> Set severity level filter to N/W/E (default N). 
-htm] Generate html-output. 
-prefix <pref> Prefix for line anchors (html output). 
-novar Disable variable checking. 
-WexprN Sets expression warning level to N. 
2 (def) Warn about any unbraced expression. 
1 Don’t warn on single commands. “if [apa] ...” is ok. 
-WsubN Sets subcommand warning level to N. 
1 (def) Warn about shortened subcommands. 
-Welse Enforce else keyword. Default 1. 
-strictappend Enforce having an initialized variable in (1)append. 
-tab <size> Tab size, default is 8. 
-header <file> Create a “header” file with syntax info for scriptfiles. 
- instrument Instrument source file for code coverage. 
-markup Markup source file with code coverage result. 
-quiet Suppress non-syntax output. 
-glob <pattern> Add matching files to scriptfiles to check. 
-H Prefix each error line with file name. 
-exitcode Return status code 2 for any error or | for warning. 


The code below has many errors, which nagel far detects and describes. Finding mismatched quotes 
is tricky, but even these can be found if you read the output carefully. 


PR $a $$ $$ 
Example 4 
Bad Script Example 

if bb is an array, not a string variable 

array set bb {one two} 

puts $bb 


if Reference an undefined variable 
puts $a 


if Forgot the value to assign to a 
set a 


set a "common error" # Should start with a semicolon 


puts "mismatched quotes’ 


dt Oops, caps lock slipped... 
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proc testProc {targl arg2] { 
puts "$argl and $arg2 are arguments" 


if failed to close an internal list 
set aList 

{element pair 1} 

{element pair 2 


Script Output 
Checking file nagerr.tcl 
Line 3: E Is scalar, was array 
Line 6: E Unknown variable "a" 
Line 9: E Unknown variable "a" 
Line 11: E Wrong number of arguments (8) to "set" 
Line 13: E 
E 


Line 13: 


Unknown variable "arg" 
Wrong number of arguments (5) to "puts" 
Argument 2 at line 17 
Argument 3 at line 17 
Argument 4 at line 17 
Argument 5 at line 17 
Line 17: E Extra chars after closing quote. 
Opening quote of above was on line 13. 
Line 17: E Extra chars after closing quote. 
Opening quote of above was on line 13. 
Line 17: E Unknown variable "arg2" 
Line 17: N Unescaped quote 
Line 18: E Unbalanced close brace found 
Line 22: E Could not complete statement. 
One close brace would complete the first line 
One close brace would complete at end of line 25. 
One close brace would complete the script body at line 27. 
Assuming completeness for further processing. 


If a procedure is defined within the Tcl script before it’s used, nagel far will report errors if the 
procedure is used incorrectly, as shown in the next example. 


——————OOOOO eee eee 
Example 5 


Bad Script Example 
proc copy {a b} { 
if Do copy 


set apa l 


# 
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t should not warn about apa below 


copy apa bepa 
## Bepa should be known now 


sev 


cepa $bepa 


## Detect $ mistake 
copy apa $bepa 


copy $apa bepa 
copy a 
copy a bec 
Nagelfar Output 
Checking file test2.tcl 
Line 6: W Found constant "apa" which is also a variable. 
Line 8: E Unknown variable "bepa" 
Line 11: E Unknown variable "bepa" 
Line 11: W Found constant "apa" which is also a variable. 
Line 14: E Wrong number of arguments (1) to "copy" 
Line 15: E Wrong number of arguments (3) to "copy" 


If the procedures are not defined within the script that is being analyzed, they can be defined in a 
. syntax file that is loaded when the scan is performed. 
When the next example is scanned, the procedure copy is reported as an unknown command. 


—_——— ee ee 
Example 6 


Script Example 


sev 


# 


apa l 
t should not warn about apa below 


copy apa bepa 


# 


sev 


tf 
co 
co 


co 
co 


PY 


a 


Script Output 


Line 
Line 
Line 
Line 


3% 


Bepa should be known now 
cepa $bepa 


Detect mistake 
py apa $bepa 
py $apa bepa 


py abc 


W Found constant "apa" which is also a variable. 


3: W Unknown command "copy" 
53 
8: E Unknown variable "bepa" 


E Unknown variable "bepa" 
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Line 8: W Found constant "apa" which is also a variable. 
Line 8: W Unknown command "copy" 
Line 9: W Unknown command "copy" 
Line 11: W Unknown command "copy" 
Line 12: W Unknown command "copy" 


The syntax file to define copy looks like this: 

d#Hfnagelfar syntax copy v n 

It can be included in the code analysis by running nagel far with the -s_ file.syntax option like 
this: 

tclsh 1s nagelfar.tcl -s fileName.syntax testFile.tcl 


With the syntax file included, the output resembles this: 


Nagelfar Output 
Line 8: N Suspicious variable name "$bepa" 
Line 9: N Suspicious variable name "$apa" 
Line 11: E Unknown variable "a" 
Line 11: E Wrong number of arguments (1) to "copy" 
E won 
E 


Unknown variable "a 
Wrong number of arguments (3) to “copy” 


Line 12: 
Line 12: 


3 DEBUGGERS 


Again, despite our best efforts, we spend a lot of time debugging code. These debuggers range from 
lightweight, compiled extensions such as Don Libes’ debug package to full-featured GUI-based 
debuggers. 

There are many debuggers not covered here, some of which are tailored to work with specific Tcl 
extensions. If the debuggers described here do not meet your requirements, use the search engine at 
http://www.tcl.tk. 


18.3.1 debug 
Language C 
Primary Site http://expect.nist.gov/ 
Contact libes @nist.gov 


Tcl Revision Supported Tcl: 7.3 and newer; Tk: 3.6 and newer 
Supported Platforms UNIX 
Other Book References Exploring Expect 
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This text-oriented debugger is distributed by Don Libes as part of the expect extension. Your 
script can load the expect extension to gain access to this feature without using the rest of the expect 
commands. The code for the debugger is in the files Dbg.c, Dbg.h, and Dbg_cf.h. With a little 
tweaking you can merge this debugger into other extensions. 

This extension adds a debug command to the Tcl language. The command debug 1 allows you 
to interact with the debugger; the command debug 0 turns the debugger off. This debugger supports 
stepping into or over procedures and viewing the stack. This debugger supports setting breakpoints 
that stop on a given line and breakpoints with a command to evaluate when the breakpoint is hit. 
The complete Tcl interpreter is available for use while in debugger mode, so you can use normal Tcl 
commands to view or modify variables, load new procedures, and so on. The on-line help lists the 
available commands in this debugger. 


dbg1.1> h 
s (C4 step into procedure 
n (#] step over procedure 
N C4] step over procedures, commands, and arguments 
Cc continue 
r continue until return to caller 
u C4] move scope up level 
d [#] move scope down level 
go to absolute frame if # is prefaced by "df" 
w show stack ("where") 
w -w [#] show/set width 
w -c [O|1] show/set compress 
b show breakpoints 
b [-r regexp-pattern] [Lif expr] [then command] 
b L-g glob-pattern] Lif expr] [then command] 
b [CLfile: ]#] Lif expr] [then command] 


f pattern given, break if command resembles pattern 
f ## given, break on line # 
f expr given, break if expr true 


f command given, execute command at breakpoint 
b -4# delete breakpoint 
b?= delete all breakpoints 


While in debugging mode, the normal prompt resembles Dbg2.3>, where the digit 2 represents 
the current stack level and the 3 represents the number of interactive commands that have been exe- 
cuted. In the sample debugging session shown next, the optional patterns and if/then statements 
are used with the break command to display the content of the variable 1st when the breakpoint is 
encountered. 
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ae 
Example 7 


Script Example 
% cat test.tcl 
proc addList {lst} { 
set total 0; 
foreach num $1st { 
set total [expr $total + $num] 
} 
return $total 
} 
proc mean {lst} { 
set sum [addList $lst] 
set count [llength $lst] 
set mean [expr $sum / $count] 
return $mean 
} 
set Ist [list 2 4 6 8] 
puts "Mean $1st : [mean $lst]" 


Debugging Session 
$> expect 
expectl.1> debug 1 
0 
expectl.2> source /tmp/test.tcl 
1: history add {source /tmp/test.tcl 
} 
dbgl.1> b -g "xset countx" if {[llength $lst] < 10} {puts "LIST: $l1st"} 
0 
dbg1.2> c 
LIST: 2 4 6 8 
3: set count [llength $lst] 
dbg3.3> w 
0: expect 
x1: mean {2 4 6 8} 
3: set {count} {4} 
dbg3.4> n 2 
3: set mean [expr $sum / $count] 
dbg3.5> w 
0: expect 
x1: mean {2 4 6 8} 
3: set {mean} {5} 
dbg3.6>c 
Mean 2468: 5 
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2 Graphic Debuggers 
There are several GUI-oriented debuggers available for Tcl, ranging from free packages to the com- 
mercial debuggers included with the ActiveState Tcl Dev Kit and Komodo IDE or the Neatware 
MyrmocoX IDE. 

Most of the debuggers are now packaged as part of an IDE like the Komodo IDE or MyrmocoX. 


| EXERCISING AND REGRESSION TESTING 


Testing a GUI is usually a manual exercise with a lot of places where an almost-clicked button or mis- 
selected menu item can change results. There are many commercial tools to regenerate a set of user 
interactions for GUI testers. 


1 TkTest 
Language Tcl/Tk 
Primary Site http:/www.cwflynt.com/tktest/ 
Contact clif@ cflynt.com 


Tcl Revision Supported Tcl: 8.4-8.6 and newer 
Tk: 8.4-8.6 and newer 
Original Author Charles Crowley, University of New Mexico 


TkTest is an application that records events that occur to Tk widgets (buttons, entry, menu, etc.) and 
will then replay these events. While recording events it can also record internal state such as variable 
contents, database records, etc. During the replay it can check that the state is the same as the recorded 
state. 

TkTest uses a small set of socket procedures to send and receive events from the application being 
tested. This requires a stub that checks that the application is being tested and has an IP address 
associated with it to be added to the test application. A stub resembles this: 


—_—_—_ S$ AS AAS aA 
Example 8 
Script Example 
if {Lset pos [lsearch $argv -test]] >= 0} { 

set pos2 [expr {$postl}] 

set TkTestAddress Llindex $argv $pos2] 

source socksend/socksend.tcl 

sockappsetup tktest.tcl 3010 $TkTestAddress 

jf Remove the -test IPAddr args 

set argv [lreplace $argv $pos $pos2] 
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This stub initiates the connection to TkTest. 
When TkTest is connected to an application, it looks like this: 


File Edit Settings 


Btatus: Connected Event Script: | 
onnectedTo:| shortTest.tcl Control Script:) 


Event Script | Control Script | 


File Edit 


Prim = =ARAaQ i jos 


0.0 --- Beginning of script --- 
0.0 --- End of script --- 


rase the entire script 


The shortTest.tcl script being examined is shown below: 


A 
Example 9 
Script Example 
if {{set pos [lsearch $argv -test]] >= 0} { 

set pos2 [expr {$postl}] 

set TkTestAddress [Llindex $argv $pos2] 

source socksend/socksend.tcl 

sockappsetup tktest.tcl 3010 $TkTestAddress 

if Remove the -test IPAddr args 


18.4 Exercising and Regression Testing 719 


set argv [lreplace $argv $pos $pos2] 
} 


## A simple application for testing/exercising tktest. 


proc clearData {} { 
global data 
foreach nm [array names data] { 
set data($nm) "" 
} 
.1f1.t delete 0.0 end 


proc GUI {} { 
set f0 [menu .bf -type menubar] 
. configure -menu $f0 
f0 add cascade -label "File" -menu $f0.file 
set [menu $f0.file] 
m add command -label "exit" -command exit 


f0 add cascade -label "Edit" -menu $f0.edit 
set [menu $f0.edit] 
m add command -label "clear" -command clearData 


set 1fl Llabelframe .1f1 -text "Entries"] 
grid $1f1 


set row 0 

foreach {ttl var} {Name name Quest quest "Favorite Language" language} { 
incr row 

set w [label $1f1.1_$var -text $ttl1] 

grid $w -row $row -column 1 

set w Lentry $1fl.e_$var -textvar data($var) ] 

grid $w -row $row -column 2 


avorite Language 
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A recording session is started by clicking the leftmost triangle button in TkTest, and then perform- 
ing a set of actions on the test application. As the actions are performed, the events are displayed in the 
TkTest’s large window. 

After filling in the fields the applications resemble this: 


File Edit Settings 


Connected Event Script: shortTest.tkr 
shortTest.tcl Control Script: 


Event Script | Control Script | 


File Edit 


D> pr idm | ~~ QA\Q) Il €|H 7) 
0.0 --- Beginning of script --- 
1.2 <Enter> .bf 
0.0 <Enter> Menu 
0.0 <Motion> .bf 
0.0 <Motion> 
0.0<Motion> . 
0.0 <Motion> 

0.1 <Motion> . 
0.0 <Motion> 
0.0<Motion> . 
0.0 <Motion=> 
0.0<Motion> . 
0.0 <Motion= 
0.0<Motion> . 
0.0 <Motion= 
0.0<Motion> . 
0.0 <Motion> 

0.0 <Motion> . 
0.0 <Motion> 
0.0<Motion> . 
0.0 <Motion> 

NN eMatians 


galahad 
seek the grail 


Clicking the leftmost magnifying glass button brings up a dialog that lets you enter the name of a 
global array to be examined. 
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File Edit Settings 


Connected | Event Script: | shortTest.tkr 
shortTesttcl | Control Script! 


Event Script | Control Script | 


File Edit 


>| > >r\iim@ | = QQ@QaQ i) Do 


0.2 <Key-e> Entry 

0.2 <Key-e> Entry 

0.2 <Key-k> Entry 

0.1 <Key-\> Entry 

0.1 <Key-t> Entry 
<Key-h> 

| Pema = ; Get Array Snapshot 

0.1 <Key\> Ent Array Name data 

/0.3 <Key-g> Cancel | Go | 

| 0.3 <Key-r> 

| 0.0 <Key-a> 

| 0.2 <Key-i> 

(0.1 <Key-I> 

0.3 <Key-Tab> Entry 

0.0 <Key-Tab> all 

|0.0 <<Traverseln> Entry 

|0.7 <Key-t> Entry 

/0.3 <Key-c> Entry 

|0.0 <Key-l> Entry 

} 0.0 ExecTcl "CheckArrayReturn {array g...the grail}}" 

0.0 --- End of script --- 


inished replaying the script 


This records the contents of the array for later comparison when the test is rerun. 


After a set of events is replayed, if there are any tests, a display resembling the following is created 


showing the results of tests: 


- 


| md Check OK (shortTest. tkr): array get data 


Save | Last Detailed 


18.5 PACKAGING TOOLS 


One of the other problems with interpreted applications is distribution and installation. Most corpora- 
tions do not want to distribute their product in an easily read script format, and interpreting the scripts 


requires that the end user has all the required interpreters and extensions on their system. 
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Wrapping an application with the Tcl interpreter solves both of these problems. The script is con- 
verted to a compiled or g-zipped format, making it difficult to read, and the correct revision of the 
interpreter is distributed with the application. The size of a wrapped Tcl application is very similar to a 
compiled application linked with the appropriate libraries. 


freewrap 
Language executable 
Primary Site http://sourceforge.net/projects/freewrap/ 
Contact freewrapmgr @ users. sourceforge.net 


Tcl Revision Supported Tcl: 8.0-8.6 and newer; Tk: 8.0-8.6 and newer 
Supported Platforms UNIX, MS Windows, Mac, Mac OS-X 


The freewrap wrapper uses the zip file feature of including an executable preamble. The 
freewrap application adds support for treating a zip file as a file system to the Tcl interpreter, and 
then adds that interpreter to a zip file, creating a compressed executable program. 

One nice feature of this technique is that if you have a copy of freewrap that was compiled on a 
target platform, you can use that copy to create an executable for that platform from any other platform. 
For instance, you can create Windows and Solaris executables on a Linux platform. 


18.5.2 Starkit and Starpack 


Language Gy. Fell 
Primary Site www.equi4.com/starkit/ 
Contact jcw @equi4.com, steve @ digital-smarties.com 


Tcl Revision Supported Tcl: 8.1-8.6 and newer; Tk: 8.1-8.6 and newer 
Supported Platforms UNIX, MS Windows, Mac, Mac OS-X 


The standard Tcl installation includes two executable programs (tc1sh and wish), a few configu- 
ration files, and several Tcl script files. The normal Tcl distribution installs all of these files in a painless 
fashion. However, if you are intending to distribute a simple application, you may not wish to make 
your end user install Tcl first. 

The tclkit package merges all of the Tcl and Tk executable programs and support files into a single 
module using a virtual file system that mirrors a directory tree within a metakit database. The package 
provides tools to wrap all files involved in an application into a single file called a Starkit (STandAlone 
Runtime Kit). This allows you to deploy an application with just two files (the TclKit interpreter and 
your kit), instead of many files. 

Starpack extends this idea and allow you to wrap both the TclKit executable and your Starkit into a 
single executable file. The program that generates Starkit and Starpack is sdx, which is available from 
www.equi4.com/starkit. Like many Tcl commands, the sdx program supports several subcommands. 


Syntax: sdx qwrap file.tcl ?name ? 


Wraps the file.tc/ script into a starkit named file.kit, suitable for evaluating 
with a tcl kit interpreter. 
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file.tcl A file with a Tcl script in it. 


name An optional name to use instead of f77e for the name of the resulting Starkit. 


$> cat test.tcl 

package require Tk 

grid [button .b -text ‘‘QUIT’’ -command exit] 

$> sdx qwrap test.tcl 

3 updates applied 

$> 1s -latr test 

-rw-r--r-- 1 clif users 64 Aug 17 16:44 test.tcl 
-rwxr-xr-x 1 clif users 746 Aug 17 16:44 test. kit 
$> ./test.kit ;# Displays a button 


Syntax: sdx unwrap file.kit 
Unwraps a Starkit into a directory named file.vfs. 


file.kit The name of a previously wrapped TclKit. 


$> sdx unwrap test.kit 

$> 1s -ltr testx 

-rw-r--r-- 1 clif users 64 Aug 17 16:44 test.tcl 
-rwxr-xr-x 1 clif users 746 Aug 17 16:44 test.kit 
test.vfs: 

total 16 

-rw-r--r-- 1 clif users 109 Aug 17 16:44 main.tcl 
drwxr-xr-x 2 clif users 4096 Aug 17 16:56 lib 


A standalone starpack can be built from the files ina . vfs directory tree with the sdx wrap command. 
The easiest way to construct this tree is to use sdx qwrap to wrap a file into a starkit, and then unwrap 
the starkit using the sdx unwrap command, and finally wrap a full standalone starpack with the sdx 
wrap command. 


Syntax: sdx wrap dirName -runtime tclkitName 


Wrap the files in dirName.vfs into a Starpack standalone, executable 
program 


dirName The prefix of a directory named dirName.vfs. All files in the 
dirName.vfs/1ib directory will be placed in the virtual file system 
built into the Starpack. 


tclkitName The name of a TclKit executable. This file can be for a platform other 
than the platform creating the wrap. Thus, you can create MS 
Windows or Linux executable programs on a Solaris 
platform, and so on. 


$> sdx wrap test -runtime tclkit.]inux 
2 updates applied 
$> 1s -ltr test* 
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-rw-r--r-- 1 clif users 64 Aug 17 16:44 test.tcl 
-rwxr-xr-xX 1 clif users 746 Aug 17 16:44 test.kit 
-rwxr-xr-x 1 clif users 2874580 Aug 17 17:03 test 
test.vfs: 

total 8 

-rw-r--r-- 1 clif users 109 Aug 17 16:44 main.tcl 
drwxr-xr-x 2 clif users 4096 Aug 17 16:56 lib 

$> ./test ;i# Displays button widget 


If an application requires several . tc] files (and perhaps a pkgIndex.tc1), they can all be placed 
in the dirName.vfs/1ib directory. Note that the tclkit provided in the - runtime option should not 
be the same tclkit used to evaluate sdx. This should be copy of the standalone tclkit. 

The sdx application has been reworked and expanded in the ActiveState TclApp wrapper. An 
ActiveTcl distribution includes TclKits named base_... which can be used with either sdx or 
TclApp. 


18.6 TCL EXTENSION GENERATORS 


Chapter 15 described how to build a Tcl extension. Although the Tcl interface is very easy to work with, 
building an extension around a large library can mean writing a lot of code. The SWIG and CriTcl 
packages allow you to construct Tcl extensions without needing to learn the details of the Tcl inter- 
face. The SWIG package is designed to create a Tcl extension from a library of existing code, whereas 
the CriTlcl package is ideal for smaller, special-purpose extensions that provide one or two new 
commands. 


18.6.1 SWIG 


Language C++ 
Primary Site www. swig.org 
Contact beazley @cs.uchicago.edu 


Tcl Revision Supported Tcl: 8.0 and newer; Tk: 8.0 and newer 
Supported Platforms UNIX (gcc), MS Windows, Mac (PowerPC) 


The SWIG (Simplified Wrapper and Interface Generator) program reads a slightly modified include 
file and generates the Tcl interface code to link to the library API that the include file defined. 
SWIG will create Tcl commands that can access pointers and structures, as well as the standard Tcl 
data types. With a command line option, SWIG can put the new commands into a private names- 
pace. SWIG can generate interfaces for almost any data construct. The package is very rich and 
complete. 

The following example demonstrates how easily an extension can be created with SWIG. This exam- 
ple shows a subset of what SWIG can do. If you have an image analysis library, it would probably have 
a function to translate points from one location to another. The function and data definitions in the 
include file might resemble the following. 
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gE.—]_ADSAD>SA AM 
Example 10 
typedef struct point-s { 
float x; 
float y; 
} point; 
int translatePoint(float xOffset, float yOffset, 
point xoriginal, point xtranslated); 


To convert the structure and function definition into a SWIG definition file, you would add the 
following items to an include (.h) file. 


e A module definition name. 
4module three_d 
e An optional command to generate the AppInit function. 
include tclsh.i 
e In-line code for the include files that will be required to compile the wrapper. 


val 
# include "“imageOps.h" 
a} 


¢ Dummy constructor/destructor functions for structures for which SWIG should create interfaces. 


When this is done, the definition file would resemble the following. 


“module imageOps 
“include tclsh.i 


#include "imageOps.h" 
a} 
typedef struct point_s { 

float x; 

float y; 

point(); 

~point(); 

} point; 

int translatePoint(float xOffset, float yOffset, 
point xoriginal, point *translated); 


This input is all SWIG needs to generate code to create the structures and invoke the translate- 
Point function. The last steps in creating a new extension are compiling the wrapper and linking with 
the Tcl libraries. 


$> swig imageOps.i 
$> cc imageOps_wrap.c -limageOps -1ltcl -ldl -1m 
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When this is done, you are ready to write scripts to use the new commands. The new extension has 
the following new commands. 


Syntax: 


Syntax: 
Syntax: 


Syntax: 
Syntax: 


Syntax: 


Syntax: 


new_point 
Create a new point structure, and return the handle for this structure. 


point_x_set pointHandle value 

point_y_set pointHandle value 
Sets the value of the member field of the point structure. 
pointHandle The handle returned by the new_point command. 
value The value to assign to this member of the structure. 


point_x_get pointHandle 
point_y_get pointHandle 


Returns the value of the member member of the point structure. 
pointHandle The handle returned by the new_point command. 


delete_point pointHandle 

Destroys the point structure referenced by the handle. 

pointHandle The handle returned by the new_point command. 
translatePoint x0ffset yOffset originalPoint translatedPoint 


Translates a point by xO0ffset and yOffset distances and 
puts the new values into the provided structure. 


xOffset The distance to translate in the X direction. 
yOffset The distance to translate in the Y direction. 
originalPoint The handle returned by new_point with the location of the 


point to translate. 


translatedPoint The handle returned by new_point. The results of the 
translation will be placed in this structure. 


A script to use these new commands would resemble the following. 


] 


Example 11 


Script Example 
i## Define the original point 
point original 


original 


configure -x 100.0 -y 200.0 


i## Create a point for the results 

point translated 

i## Perform the translation 

translatePoint 50 -50 original translated 
## Display the results 
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puts “translated position is: \ 
[translated cget -x] [translated cget -y]" 


Script Output 

translated position is: 150.0 150.0 

= 

18.6.2 CriTel 

Language Tcl 

Primary Site www.equi4.com/critlib/ 

Contact jcw @equi4.com, steve @ digital-smarties.com 

Tcl Revision Supported Tcl: 8.0-8.6 and newer; Tk: 8.0-8.6 and newer 

Supported Platforms UNIX (gcc), MS Windows (Mingw) 


One of the advantages of Tcl is that you can do your development in an easy-to-use interpreter, 
profile your code, and then recode the computer-intensive sections in C. CriTcl (Compiled Runtime In 
Tcl) makes this very easy. 

CriTcl adds a new command critcl::cproc to allow a script to define in-line C code. When the 
script needs to use the C function defined by the cproc command, it is either generated and compiled 
on the fly, or loaded from a shared library generated when the application was run previously. 


Syntax: critcl::cproc name arguments return body 
Define an in-line C procedure. 


name The name of the new Tcl command to create from the C code. 
arguments AC function argument definition. 

return The return type of the C function. 

body The body of a C function. 


critcl::cproc add {int x int y} int { 
return x + y; 


} 


The next example shows the same procedure for generating a simple 8-bit checksum written in 
both C and Tcl. Note in the next example that the char pointer is defined as a char*. CriTcl expects 
single-word data types. 


Example 12 
Script Example 
package require critcl 
proc checksum {txt } { 
set sum 0 
foreach 1 Esplit $txt ""] { 
binary scan $1 c val 
set sum [expr ($sum >> 1) + ($sum % $val)] 
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return $sum 
} 
critcl::cproc checksum_c {charx txt} int { 
int sum = 0; 
char x1; 
] = txt; 
while (*l != 0) { 
sum = (sum >> 1) + (sum *% *1); 
ae 


} 


return sum; 


} 
set data "12345678901234567890123456789012345678901234567890" 


puts "Tcl Checksum: [checksum $data]" 
puts "C Checksum: Echecksum_c $data]" 
puts "Pure Tcl takes [time {checksum $data} 1000]" 
puts "C code takes [time {checksum.c $data} 1000]" 


Script Output 
Tcl Checksum: 53 
C Checksum: 53 
Pure Tcl takes 1484 microseconds per iteration 
C code takes 2 microseconds per iteration 


CriTcl is deployed as a single cross-platform Starpack, which is interpreted using TclKit. CriTcl 
is also able to generate packaged extensions (with cross-platform support) suitable for inclusion 
in Starkits or other wrapping mechanisms. There is more information about these packages on the 
companion website. 


3.7 INTEGRATED DEVELOPMENT ENVIRONMENTS 


The Tcl language is easy to work with, and the interpreted nature of the language makes the edit/test 
sequence quick. This leads many folks to stick with traditional development tools such as the Emacs 
Tcl mode or other simple text editors. 

There are several open source IDEs (for example, Eclipse) that support Tcl, as well as at least two 
commercial IDEs. Again, if you do not find anything listed here that suits your needs, check for new 
developments at www.tcl.tk or comp.lang.tcl.announce. These packages have some unique and some 
similar features. The following table provides an overview of the functionality. 


Feature Komodo MyrmecoX 
Highlighted commands Y Y 
Command syntax hint Y Y 
Command completion Pull-down = Pull-down 


Automatic quote/brace/bracket Y N 
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Show matching quote/brace/bracket Y N 

Auto indent Y N 

Highlight runtime errors Y N 

Syntax checker Y Y 

Code browse N N 

Expand/shrink code segments Y N 

Integrated console N Y 

Integrated debugger Y Y 
18.7.1 KomodoEdit 

Language compiled 

Primary Site www.activestate.com/komodo-edit/ 

Contact Komodo-feedback @ ActiveState.com 


Tcl Revision Supported Tcl: 8.0-8.6 and newer; Tk: 8.0-8.6 and newer 
Supported Platforms Linux, MS Windows, Mac OS/X 


Komodo Edit is the smart editor portion of the full Komodo IDE. It lacks many of the features of the 
full IDE, while still providing enough features to be useful. The included features include command 
completion, command hints, syntax highlighting, quote/brace/bracket matching, user defined macro 
expansions and running a script from within the editor. The command hints make it especially useful 
to the person learning Tcl/Tk. 

When you open a new edit session, Komodo Edit will prompt you for the type of file you are editing. 
This selection loads the template that will be used for name completion, popup hints and informational 
colors. 


Categories Templates 
(All Languages | |[=jPerl Module (00) 
- | |(E)PHP 
(Mozilla Development [=|Python 
My Templates [E|RHTML 
> samples [EjRuby 
(web [=|Smarty 
Li 


| [iTemnlateTaolkit | 


Filename: (| v 


Directory: | root v Local... Remote... 


®| Help Open Template Folder @ Cancel @ Open 
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While entering new text, Komodo Edit supplies completion hints and syntax reminders as shown 
in the next two images. 


File Edit Code Navigation View Project Tools Help 
Ue es yd 


testKomodo.tcl* 


File Edit Code Navigation View Project Tools Help 


UGH es ¢50 


testKomodo.tcl* 
1 : 


18.7.2 Komodo 


Language compiled 
Primary Site www.activestate.com/komodo-ide/ 
Contact Komodo-feedback @ ActiveState.com 


Tcl Revision Supported Tcl: 8.0-8.6 and newer; Tk: 8.0-8.6 and newer 
Supported Platforms Linux, MS Windows, Mac OS/X 


The Komodo IDE supports many languages, including Perl, Python, Tcl, PHP, XSLT, JavaScript, 
Ruby, Java, and others. It includes an integrated debugger, GUI layout tool, and a tool for testing and 
tuning regular expressions. 

The context-sensitive editor will underline sections of code with syntax errors while you are typ- 
ing them, to provide immediate feedback about problems. If you pause, the GUI will open a pop-up 
syntax reminder, or provide a pull-down menu to select subcommands. The built-in debugger supports 
breakpoints, stack display, variable monitoring, and other features. 

The following image shows Komodo being used to debug an application. 

The mean procedure is rolled up to save space in the edit window. The execution is currently halted 
at the breakpoint on line 9, with the bottom debug window displaying the current state of the program. 
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n Wiew Debug Project Tools 


~ UB. e@ etl s°= Pe ovadQ eve -- es 


Start Page | |testKomodo.tcl ® 


lsh "$6" ${1+"$@"} 
SE] proc makeGUI {} { 
label .1 -text "Guess a number between 1 and 10" 
entry .e -textvar guess 
button .b -text "Ready" -command checkGuess 
grid .l .e 


grid .b testKomodo.tel 


} 
proc checkGuess {} { Guess a number between 1 and 10/2 
global guess number Ready | 
r if {$guess == $number} { —————— 

tk_messageBox -type ok -message "You Win" 


} else { ©) You Lose 
tk_messageBox -type ok -message "You Lose" i=! 


it 


} 
set number [expr {int(rand()*10)}] 
makeGUI 


Name Type 


$guess string 
$number string 


atch | Local | Global J és © | Output | Call Stack HTML 
@ checkGuess = < JUTR-8) (in: 17'eol: 57 Sel:42ch,1In ¢ Tel 


18.7.3 MyrmecoX 


Language Compiled 
Primary Site www.neatware.com 
Contact changl@ neatware.com 


Tcl Revision Supported Tcl: 8.0-8.6 and newer;Tk: 8.0-8.6 and newer 
Supported Platforms MS Windows 


The MyrmecoX IDE extends the TclPro tool set (including the byte-code compiler) to work within 
the framework of an IDE. The IDE supports context-sensitive editing with knowledge of the following 


packages. 
Kernel/Util 
GUI Tcl/Tk8.3.4, TclX/TkX 8.3, Tcllib0.8 
BLT 2.4, BWidget 1.2.1, IWidget 3.0, Img 
.2, Tktable 2.6, tkWizardl.0Om xWizard 2.0 
Object Lincr Tcl] 3.2, Lincr Tk] 3.2 
Web TclSoap 1.6.1, TclXML 2.0, TclDom 2.0 
Database TcIODBC 2.1, Oratcl 3.3. 


_— 
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COM 
Automation 
Java 


Security 


CHAPTER 18 Programming Tools 


TCOM (Windows only) 


Expect 5.2.1 (Windows only) 


TclBlend 
PSs Lat 


The package is developed for MS Windows and supported on all flavors of Windows, including 
XP. Being compiled, this IDE is suitable for low-end Pentium systems, as well as 64-bit Itaniums. 


; 


oO 
oF 


8 BOTTOM LINE 


There are many tools available to help you develop Tcl/Tk applications. Information about tools 
and extensions can be found at www.tcl.tk, the announcements in the newsgroup comp.lang.tcl, 
the FAQs at www. purl.org/NET/Tcl- FAQ, and the Tcler’s Wiki at http://mini.net/tcl/. 

You can reformat your Tcl code with frink. 

You can check your code for syntax errors with tc]Check, frink or nagel far. 

You can debug Tcl scripts with debug, MyrmecoX or ActiveState Tcl Dev Kit Debugger. 

You can convert scripts to executable binary code with Freewrap, or TclKit. 

You can develop extensions quickly with the SWIG extension generator. 

You can improve an application’s speed by embedding C code using CriTcl. 

Tcl applications can be developed using the Komodo, or MyrmecoX IDE tools. 


CHAPTER 


Tips and Techniques 


Every language has its strengths and weaknesses, and every programmer develops ways to take advan- 
tage of the strengths and work around the weaknesses. This chapter covers some of the ways you can 
use Tcl more effectively to accomplish your tasks. This chapter discusses debugging, some common 
mistakes, some techniques to make your code more maintainable, and a bunch of odds and ends that 
have not been covered in previous chapters. 


DEBUGGING TECHNIQUES 


Testing and debugging a program are some of the most tedious parts of computer programming. The 
testing and debugging phase of a project can easily take more time than it took to write the application. 

Testing includes both checking that the code runs at all, that it runs correctly under all circum- 
stances, and that it runs the same way it did before you made changes. 

The debuggers discussed in Chapter 18 are very useful tools but are not the only way to debug code. 
Tcl has some features that make it easy to debug code. The interpreted nature of Tcl makes it easy to 
do much of your debugging without a debugger. Since there is no separate compilation stage in Tcl, 
you can easily add a few debugging lines and rerun a test. The following sections discuss techniques 
for debugging code without a debugger. 


19.1.1 Reading the Error Messages 
The first step to debugging a Tcl script is to examine the Tcl error output closely. Tcl provides a verbose 
error information that can lead you to the exact line where a coding error occurs. 

Tcl error messages consist of a set of lines. The first line will describe the immediate cause of 
the error (incorrect number of arguments, invalid argument, undefined variable, etc.). The rest of the 
message describes more details about where the error occurs. 

For example, this procedure has a fairly common error—the closing brace and bracket are in the 
wrong order: 


proc hasError {a} { 
return Lexpr {$at2]} 
} 


The error message is: 


missing close-bracket 
while executing 
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"return [expr {$a+2]}" 
(procedure "“hasError" line 2) 
invoked from within 

"hasError 1" 


The first line describes the error (missing curly bracket), and the rest of the lines show the exact 
line in the program 


return [expr {$a+2]} 


and where that line occurs (second line in the hasError procedure). 
Here are a few of the common error messages and a description of the code that generates them. 


* wrong # args: should be 
A command or procedure has been called with too few or too many arguments. This is 
commonly caused by forgetting to put braces or quotes around a string. 
This error is also common in code that’s attached to a button, an after event or some other 
command that allows delayed evaluation. 
This code shows a button that will generate an error when clicked. 


set result "a b" 
button .b -text set -command "set x $result" 


This example looks reasonable, but the command to be evaluated when the button is clicked 
is created by substituting the $result and concatenating the values into a string resembling this: 
set xX a Db. 

The recommended way of creating a button like this is to use the 1 ist command to maintain 
grouping: 

set result "a b" 
button .b -text set -command [list set x $result] 


e missing 
e missing close-brace 
e missing close-bracket 
Your code has an unterminated string that starts with a double-quote. The usual causes of this 
are typos (not hitting shift fast enough and having a double quote at one end of a string and a single 
quote at the other), having a space after a back-slash line continuation character, or mismatching 
the open/close pairs of a set of nested quotes, braces and brackets. 
Here are some examples of lines that would generate one of these errors. 


set rtn "there is a space after the backslash \ 
causing this to generate an error" 

puts "Missing close quote 

puts "mismatched quote and brace} 

puts "should be double quote to close’ 


¢ can’t read no such variable 
There is a $varName in your code for which varName has never been set. 
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This can happen: 

e because you were reworking code and forgot to initialize a variable. 

e because a global scope variable is referenced in a procedure without declaring it global. 

e because a procedure invoked from a widget did not declare the widget’s -textvariable to be 
in global scope. 
because code is being evaluated outside the scope in which it was created. Code connected with 
a button, after event, etc. is evaluated in the global scope (unless a namespace or class scope 
is assigned) even if the widget is created within a procedure or method. Procedure scope local 
variables will no longer exist after the GUI has taken control of the application. 


set globalVar 1 


if Fails because of missing "global globalVar" 
proc hasError {} { 

puts "$globalVar" 
} 


i## The entry widget is OK, 

# but clicking the button will cause an error. 
entry .e -textvariable globalVar 

button .b -text "generateError"™ -command hasError 


# This button references a local variable. 


proc makeBadButton {} { 
set xx "local variable" 
button .b -text "throw error" -command "puts $xx" 
grid .b 

} 


e invalid command name 
The first word on a command line is not a valid command or procedure name. This is most often 
caused by mis-typing a command name, or forgetting to source or package require the Tcl 
code that defines a command or procedure. 

e syntax error in expression "...": variable references require 
preceding $ 


invalid bareword 


This error is generated by the expr command. It’s caused when you try to do arithmetic on a string. 
The usual causes are that you forgot to put a dollar-sign on a variable name or that a variable that 
should hold a number was assigned a string value. 


19.1.2 Instrumenting Code to Generate Log Files 


The Tcl error return provides information about syntax errors and sudden death failures. The more 
insidious problems are the ones that only occur after an application has run for a while. 
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If the problem appears the first time a condition occurs, it can be easy to diagnose with a GUI 
debugger. If it occurs after a period of running, you may need to track the program’s internal state and 
generate log files to figure out when a data corruption or an incorrect procedure call occurs. 


Examine the Call Stack with the info level Command 
Sometimes a bug appears in a procedure that is invoked with bad arguments. In order to fix the bug, you 
need to know which code invoked the procedure. You can learn this with the info level command. 


Syntax: info level ?/evelValue 
If invoked with no /eve/ Value argument, info level returns the stack level 
currently being evaluated. If invoked with a ]eve] Value argument, info level 
returns the name and arguments of the procedure at that stack level. 


levelValue If levelValueis a positive value, it represents the level in the 
procedure stack to return. If it is a negative value, it represents a 
stack location relative to the current position in the stack. 


The next example shows info level being added to a procedure where an error is seen. The 
actual cause of the error is the procedure call in the causesError procedure where a dollar-sign is 
missing. 


$$ $ $$ i i 


Example 1 
Script Example 


proc reportsError {a} { 
it Added info level to track how this procedure is called. 
puts "“reportsError called as: [info level -0]" 
puts "reportsError called from: [info level -1]\n" 


return [expr {$a + 2}] 
} 


proc causesError {b} { 
reportsError b 
} 


proc worksOK {c} { 
reportsError $c 
} 


worksOK 2 
causesError 3 


Script Output 


reportsError called as: reportsError 2 
reportsError called from: worksOK 2 
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reportsError called as: reportsError b 
reportsError called from: causesError 3 


can’t use non—numeric string as operand of "+" 
while executing 
"expr {$a + 2}" 
(procedure "reportsError" line 6) 
invoked from within 
"reportsError b" 
(procedure "causesError" line 2) 
invoked from within 
"causesError 3 " 
(file "foo.tcl" line 19) 


Examine Variables When Accessed with trace Command 

Sometimes you know that a variable has an invalid value by the time it is used in a procedure and 
you know its value was valid when it was defined. Between the time the variable was set and when it 
was used, something changed the value but you do not know what. The trace command will let you 
evaluate a script whenever a variable is accessed. This makes it easy to track which procedures are 
using (and changing) variables. 


Syntax: trace add variable name operations command 
Puts a trace on a variable that will cause a procedure to be evaluated whenever the 
variable is accessed. 
name The name of the variable to be traced. 


operations Whenever a selected operation on the variable occurs, the command 
will be evaluated. Operation may be one of: 


array Evaluate the command whenever the variable is accessed 
via the array command. 


read Evaluate the command whenever the variable is read. 

write Evaluate the command whenever the variable is written. 

unset Evaluate the command whenever the variable is unset. 

command A command to evaluate when the variable is accessed. The 

command will be invoked with the following three arguments. 

name The name of the variable. 

index If the variable is an associative array, this will be the 
index of the associative array. If the variable is a 
scalar variable, this will be an empty string. 


operation A single letter to denote the operation that triggered 
this evaluation. 
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The following example shows how the trace command can be used with a procedure 
(traceProc) to display part of the call stack and the new value when a variable is modified. If you find 
yourself using traces frequently, you may want to examine the OAT extension and Tc1 Prop package 
from the University of Minnesota (www.cs.umn.edu/research/GIMME/clprop.html). The OAT exten- 
sion enhances the t race command, allowing all Tcl and Tk objects (such as widgets) to be traced. The 
Tcl Prop package (among other features) lets you watch for variables being changed with a single line 
command instead of needing to declare a script. 


——— eee ee eee 
Example 2 


Script Example 


i## The procedure to invoke from trace 


proc traceProc {varName index operation} { 
upvar $varName var 
set lvl Linfo level] 
incr lvl -1; 
puts "Variable $varName is being modified in: 
‘Linfo level $lvl1]’" 
if {$lvl > 1} { 
incr lvl - 
puts " Which was invoked from: ‘Linfo level $lv1]’" 
} 
puts "The current value of $varName is: $var\n" 
} 


i## Example Script using traceProc 


it A procedure to modify the traced Variable 


proc modifyVariable {newVal} { 
global tracedVariable 
set tracedVariable $newVal 

} 


i## A procedure to call the variable changing procedure, 
i## to demonstrate getting information further up the 
i## call stack. 


proc otherProc {newVal} { 
modifyVariable $newVal 


} 


if A variable to watch. 
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global tracedVariable 
if Create a trace on the tracedVariable variable 
trace variable tracedVariable w traceProc 


## Now, modify the variable, twice within procedures, 
## and once from the global scope. 


i## This will modify the variable two levels deep 
dt in the call stack. 


otherProc One 
# This will modify the variable one level down the call stack. 
modifyVariable Two 


i## Notice that the change from global scope reports itself as 
i## coming from the ‘traceproc’ command 


set tracedVariable Three 


Script Output 
Variable tracedVariable is being modified in: 
‘modifyVariable One’ 
Which was invoked from: ‘otherProc One’ 
The current value of tracedVariable is: One 


Variable tracedVariable is being modified in: 
‘modifyVariable Two’ 
The current value of tracedVariable is: Two 


Variable tracedVariable is being modified in: 
‘traceProc tracedVariable {} w’ 
The current value of tracedVariable is: Three 


19.1.3 Run Script in Interactive Mode 


You can invoke a script from a tclsh or wish interpreter with the source command. When a script 
is invoked with the source command, the interpreter returns you to the interactive prompt instead of 
exiting on an error. The tkcon program described in Chapter 2 is an excellent tool to use for interactive 
mode debugging. The ability to recover previous commands and edit them slightly makes it easy to 
run multiple tests and observe how a procedure behaves. 
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If your script requires command line arguments, you can set the argv and argc variables before 
you source the script, as shown in the following example. The example shows a simple debugging 
session that tries to open a nonexistent file, and then evaluates the procedure that would be called if a 
valid file name were provided. 


OOOO” —nn— —  ay-E>~ 
Example 3 


Script named interactive.tcl 
proc processLineProcedure {line} { 
puts “Processing \"$line\"" 


} 


puts "There are $argc arguments to this script" 
puts "The arguments are: $argv" 


set fileName [lindex $argv 0] 
set infile [open $fileName "r"] 
while {!Leof $infile]} { 
set len [gets $infile line] 
if {$len > 0} { 


processLineProcedure $line 


} 


Interactive Session Output 


% set argv BadFile 

BadFile 

% set argc 1 

1 

% source interactive.tcl 

There are 1 arguments to this script 

The arguments are: BadFile 

couldn’t open "BadFile": no such file or directory 
% set argv interactive.tcl 

interactive.tcl 

% source interactive.tcl 

There are 1 arguments to this script 

The arguments are: interactive.tcl 

Processing "proc processLineProcedure {line} {" 
Processing " puts "Processing \"$line\""" 
Processing "}" 

Processing " " 

Processing "puts "There are $argc arguments to this script"" 
Processing "puts "The arguments are: $argv"" 
Processing "set fileName [lindex $argv 0]" 
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Processing "set infile [open $fileName "r"]" 
Processing "while {![Leof $infile]} {" 
Processing " set len [gets $infile line]" 
Processing " if {$len > 0} {" 

Processing " processLineProcedure $line" 
Processing " }" 

Processing "} " 


4 Use puts to Print the Value of Variables or Lines to Be Evaluated 


This technique may not be elegant, but it works in all environments. You may need to print the data 
to a file instead of the screen if you are trying to debug an application that runs for a long time, 
does something strange, recovers, and continues running. Some of the variants on using puts to track 
program flow and variables include: 


A Conditional puts in a Procedure 
This technique is useful while you are in the latter stages of debugging a system. With this technique 
you can leave your debugging code in place, while confirming the behavior without the extra output. 


proc debugPuts {args} { 
global DEBUG 
if { Linfo exists DEBUG] && $DEBUG } { 
puts "$args" 


A Bitmapped Conditional 

A bitmap can be used to control how much information is printed while the script is running. This is 
another technique that is useful when you do not always want to see a lot of output, but for tracking 
down some bugs you need all the help you can get. 

The next example shows a procedure that will print different amounts of information, depending on 
the value of stateArray (debugLevel ). If bit 8 is set, a call stack is displayed. Note that a positive 
(absolute) level is used for the info 1evel command rather than a negative (relative) level. This is a 
workaround for the fact that Tcl generates an error when you try to access level 0 via a relative level 
offset but will accept 0 as an absolute level. 

For example, a procedure that is called from the global level is at level 1 (as returned by [info 
level ]). Ifthe info level command is invoked within that procedure as info level -1, Tcl will 
generate an error. However, if the info level command is invoked as info level 0, Tel will 
return the procedure name and argument that invoked the procedure. 


OOOO —n—n—n— amy»: 
Example 4 
Script Example 


proc debugPuts {args} { 
global stateArray 
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i## If low order bit set, print the message(s) 


if {$stateArray(debugLevel) & 1} { 
puts "DEBUG Message: $args" 
} 


i## If bit two is set, print the proc name and args that 
dt ~invoked debugPuts 


if {$stateArray(debugLevel) & 2} { 
set level [info level] 
incr level -1l 


puts "DEBUG Invoked from:: [info level $level]" 
} 


## If bit four is set, print the contents of stateArray 


if {$stateArray(debugLevel) & 4} { 
foreach index Larray names stateArray] { 
puts "DEBUG: stateArray($index): $stateArray($index)" 
} 
} 


# If bit 8 is set, print the call stack 


if {$stateArray(debugLevel) & 8} { 
set level [info level] 
for {set 1 1} {$1 < $level} {incr 1} { 
puts "DEBUG CallStack $1: [info level $1]" 


} 
iHE Example of use 
proc topProc {argl arg2} { 
lowerProc three four five 
} 
proc lowerProc {args} { 
debugPuts "Message from a proc called from a proc" 


} 


set stateArray(debugLevel) 15 
topProc one two 
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Script Output 
DEBUG Message: {Message from a proc called from a proc} 
DEBUG Invoked from:: lowerProc three four five 
DEBUG: stateArray(debugLevel): 15 
DEBUG CallStack 1: topProc one two 
DEBUG CallStack 2: lowerProc three four five 


Printing Every Line 

To debug some nasty problems, you may want to display each line before it is evaluated. Sometimes, 
seeing the line with the substitutions done makes the script’s behavior obvious. You can modify your 
script to display each line before executing it by duplicating each line of code and adding a string 
resembling 


puts "WILL EVAL: 


to the beginning of the duplicated line, and a close quote to the end of the line. This modification is 
easily done with an editor that supports macros (such as Emacs). Alternatively, you can modify your 
script with another Tcl script. The caveat with this technique is to be careful that you do not accidentally 
perform an action within your puts. Consider the following example. 


—e—————?:°:72? OO _ _ _—___eee—— ee sa""” 
Example 5 


d## This will evaluate the modifyDatabase procedure. 

# It will print the status return, not the procedure call. 
puts "WILL EVAL set status [modifyDatabase \$newData]" 

## This prints the command and the value of newData 

puts "WILL EVAL: set status \[modifyDatabase $newData\]" 
set status [modifyDatabase $newData]} 


19 


.1.5 Extract Portions of Script for Unit Testing 


Since Tcl does not have a separate compilation stage, unit testing can be more easily performed in Tcl 
than in languages such as C, which might need to have more of the program infrastructure in place in 
order to link a test program. 


19.1.6 Attach a tkcon Session to Application 


The tkcon application can attach itself to another running a wish interpreter, providing a console 
interface to a running application. With this console you can examine global variables, check the status 
of after events, interact with windows, and so on. This is an excellent way of examining the state of 
an application running outside a debugger that displays an unexpected error. The following illustration 
shows how to attach a TkCon console to another wish application. 
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The menu to attach to another application is under the Console menu selection. The image below 
shows TkCon being attached to the taskbar.tc1 application. 


File Console| Edit Interp Prefs History Help 


loadi Main Console ents added 


auto] New Console ctri-N 7 
buffe ine length: unlimited 


Main NewTab Ctrl |oig.6b1.2 / Tk8.6b1.2) 
(clif Delete Tab 
Close Console Ctri-w 


Clear Console Ctrl-l 


Make Xauth Secure 


AttachTo.. __—P Interpreter 


*« None (use local slave) Ctrl-1 


Namespace 
Socket Foreign Tk Interpreters 
Display taskbar.tcl 


tkcon Interpreters 
Main (tkeon) Ctrl-3 
x slave slave ¢ Main slave (tkcon #2) 


FIGURE 19.1 
TkCon being attached to the taskbar.tcl application. 


Note that TkCon can only attach itself to a running task when using X-Windows. When using 
Microsoft Windows, the console command can be run within an application to get similar control. 


19.1.7 Create a Console Window under Windows 


The Windows distributions for Tcl/Tk include a console command. 
The command console show will create a console window, and console hide will remove the 


window. 


19.1.8 Create a Command Window to Interact with Your Application 


If you cannot use the tkcon program or the console command, you can add code to a script that will 
allow you to evaluate commands within the running application and display results. 
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The makeInteractionWindow procedure in the following example creates a new top-level win- 
dow that accepts Tcl commands, evaluates them, and displays the results. The images show this 
procedure being used to examine a radiobutton application. 


———ersrshonoerrrn 
Example 6 


Interaction Window Example 


i## Create a window to use to interact with the running script 
proc makeInteractionWindow {} { 
## Can’t have two toplevels open at once. 


if {Cwinfo exists .topInteraction]} {return} 


i## Create a toplevel window to hold these widgets 
set topWindow [toplevel .topInteraction] 


i## Create an entry widget for commands to execute, 
i## and a label for the entry widget 


set cmdLabel [label $topWindow.cmdLabel -text "Command" ] 


set cmd [entry $topWindow.cmd -textvariable cmdString \ 
-width 60] 


grid $cmdLabel -row 0 -column 0 
grid $cmd -row 0 -column 1 -columnspan 3 


i## Create a scrolling text window for the command output 


set outputLabel [label $topWindow.outputLabel \ 
-text "Command Result" ] 


set output [text $topWindow.output -height 5 -width 60 \ 
-relief raised] 


set sb [scrollbar $topWindow.sb -command “$output yview" ] 
$output configure -yscrollcommand "$sb set" 


grid $outputLabel -row 1 -column 0 
grid $output -row 1 -column 1 -columnspan 3 
grid $sb -row 1 -column 4 -sticky ns 


i## Create buttons to clear the command, 
jf execute the command and 
# close the toplevel window. 


set clear [button $topWindow.clear -text "Clear Command" \ 
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-command { set cmdString "" }] 


i# The command for the $go button is placed in quotes to 
i## allow "$output" to be replaced by the actual output 

it window name. "$output see end" scrolls the window to 
it =the bottom after each command (to display the command 
## output). 


set go [button $topWindow.go -text "Do Command" \ 
-command "$output insert end \"\Cuplevel #0 \ 
\Llist eval \$cmdString\J\n\J\"; \ 
$output see end; \ 
"] 


set close [button $topWindow.close -text "Close" \ 
-command "destroy $topWindow" J 


grid $clear -row 2 -column 1 
grid $go -row 2 -column 2 
grid $close -row 2 -column 3 


if bind the Return key in the command entry widget to 
if behave the same as clicking the $go button. 

i## NOTE: <Enter> is the “cursor enters widget" 

i## event, NOT the Enter key 


bind $cmd "<Return>" "$go invoke" 


dt 

it Example of interaction window 

dt 

if {[lsearch $argv -debug] != -1} { 


makeInteractionWindow 
} 


i## Update the displayed text in a label 


proc updateLabel {myLabel item} { 

global price; 

$myLabel configure -text \ 

"The cost for a potion of $item is $price gold pieces" 
} 


dt Create and display a label 
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set 1 [label .1 -text "Select a Potion"] 
grid $1 -column 0 -row 0 -columnspan 3 


# A list of potions and prices 


set itemList [list "Cure Light Wounds" 16 \ 
"Boldness" 20 \ 
"See Invisible" 60] 

set position 0 


foreach {item cost} $itemList { 
radiobutton .b_$position -text $item -variable price \ 
-value $cost -command [list updateLabel $1 $item] 
grid .b_$position -column $position -row 1 
incr position 
} 


Script Output 


interactWin.tel 
Select a Potion 
“ Cure Light Wounds © Boldness © See Invisible 


topInteraction 


Command 


Command Result 


Clear Command | Do Command Close 


19.1.9 Use a Second wish Interpreter for Remote Debugging 


The send command allows you to send a command from one wish interpreter to another. The com- 
mand will be evaluated in the target interpreter and the results will be returned to the source interpreter. 
This feature lets you use one wi sh interpreter in interactive mode to debug a script running in another 
interpreter. You can display variables, evaluate procedures, load new procedures, and so on. 

Syntax: send interp cmd 


Send a command to another wi sh interpreter, and return the results of that command. 
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interp The name of the destination interpreter. You can get a list of the wish 
interpreters currently running on a system with the winfo interps 
command. 


cmd A command to be evaluated in the destination interpreter. Remember to 
enclose the cmd string in curly braces if you want substitutions to be 
performed in the destination interpreter, not the source interpreter. 


All of the preceding techniques can be done in a remote interpreter using the send command. You can 
print out data, invoke procedures, check the state of the after queue, or even source new versions 
of procedures. Note that using the send command on a UNIX system requires that you use xauth 
security (or build wish with a reduced security). Under Windows, versions of Tk prior to 8.1 do not 
support the send command. 


19.2 TCL AS A GLUE LANGUAGE: THE exec COMMAND 


Although almost any application can be written in Tcl, not all applications should be written in Tcl. 
Some applications should be written using Tcl with an extension, and some should be written using Tcl 
as a glue language to join other standalone programs. 

Scripting languages are extremely useful for applications that require gluing several pieces of func- 
tionality into a new application. They are less well suited to creating base functionality such as the 
following. 


e Arithmetic-based algorithms (generating checksums or compressing files) 
e Large data applications (subsampling images) 
¢ Controlling hardware (device drivers) 


Tcl/Tk’s strength is how easy it makes merging several libraries and standalone programs into a 
complex application. This merging can be done by creating new Tcl extensions or by using Tcl to 
glue several standalone programs into a new application. If the functionality you need involves several 
functions and is available in an existing library, it is probably best to make a Tcl extension wrapper 
to access the library. See Chapter 15 on writing extensions and Chapter 18 on the SWIG and CriTcl 
packages for automating creating extensions from libraries. 

The extensions you create can either be linked into a new interpreter or merged at runtime with 
the load command. Note that you can use the 1oad command only if your operating system sup- 
ports dynamically loaded libraries (. So under Linux and Solaris, .d11 under Windows). If standalone 
applications exist that perform a subset of what you need, you can use these existing applications with 
a Tcl script to control and extend them to perform the tasks you need done. 

Many applications are easily written using Tcl and extensions for some functionality, and invoking 
standalone programs for other functionality. For example, I’ve used a Tk script to control the PPP 
connections on a UNIX system. It used the BLT extension to create an activity bar chart, invoked 
several standalone programs to initiate PPP connections and monitor the activity, and had some Tcl 
code to collect the data from various sources and report the number of connection hours. 

The caveat with calling standalone programs from your script is that it can limit the portability of 
the script. For instance, a script that uses ps to monitor active processes and display the top CPU users 
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will require different ps arguments for BSD and System V-based UNIXes and will not run at all on a 
Macintosh or Windows platform. 

The command that lets you merge existing standalone programs into a new application is the exec 
command. The exec command will invoke new programs in a subprocess and return the program 
output to the Tcl interpreter as the result of the command. If the subtask exits with a non-zero status 
(an error status), the exec command will generate an error. You can invoke a single program with the 
exec command, or a series of commands where the output of one program becomes the input to the 
next program with the UNIX pipe symbol (|). The argument to the exec command is either an exec 
option, a command to execute as a subprocess, an argument for the commands, or a pipeline descriptor. 


Syntax: exec ?-options? argl ?arg2...argn? 
Execute arguments in a subprocess. 
-options The exec command supports two options: 


-keepnewline Normally, a trailing newline character is deleted 
from the program output returned by the exec 
command. If this argument is set, the trailing 
new! ine is retained. 


ee Denotes the last option. All subsequent arguments 
will be treated as subprocess program names or 
arguments. 
arg* These arguments can be either a program name, a program argument, or 
a pipeline descriptor. There are many pipeline descriptors. Some of the 
commonly used ones are: 


| Separates distinct programs in the command line. The 
standard output of the program on the left side of the 
pipe symbol (—) will be used as the standard input for 
the program on the right of the pipe symbol. 


< fileName The first program in the list will use the content of 
fileName as the standard input. 


> fileName The standard output from the last program in the list 
will be written to f7 ]eName. 


The following examples create compressed archives of files in a directory under UNIX or Windows 
using the exec command. 


19.2.1 Creating a G-zipped tar Archive under UNIX 


——— eho 
Example 7 
Script Example 


# This script is called with the name of a directory to 
df archive as the first argument in the command line, 
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if and the name of the archive as the second argument. 


set directory [lindex $argv 0] 
set archive [lindex $argv 1] 


it Get a list of the files to include in the archive. 
set fllst [glob $directory/*] 
i## Create the tar archive, and gzip it. 


eval exec tar -cvf $archive $fllst 
exec gzip $archive 


19.2.2 Creating a Zip Archive under Windows 


—————— eee ee eee 
Example 8 


i## This script is called with the name of a directory to 
i## archive as the first argument in the command line, 
if and the name of the archive as the second argument. 


set directory [lindex $argv 0] 
set zipfile Llindex $argv 1] 

i## The file "distfiles" will contain a list of files for 
if this archive. 


set outfl [open distfiles "“w"] 
dt Get a list of the files to include in the archive. 


set fllst [glob $directory/*] 


if And write that list into the contents file, one 
i## filename per line 


foreach fl $fllst { 
puts $outfl "$f1" 


} 


close $outfl 
i## Execute the winzip program to make an archive. 
eval "exec C:/winzip/winzip32.exe -a $zipfile @distfiles" 
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19.3 COMMON MISTAKES 

There are several common mistakes programmers make as they learn Tcl. Cameron Laird 
has collected many of these from the questions and answers posted in comp.lang.tcl, at 
http://phaseit.net/claird/comp.lang.tcl/fmm.html. This section is a sampling of common errors not 
discussed in the previous chapters. 


19.3.1 Problems Using the exec Command 


The previous description of the exec command looks straightforward, but there are some common 
mistakes people make trying to use the exec command. 


The tclsh Shell Is Not the UNIX Shell 

Many problems appear when people try to use shell expansions or shell escapes with the exec com- 
mand. For example, the wrong way to write the exec tar... command in the previous example 
would be: 


exec tar -cvf $archive $directory/* 


In this case, the tclsh shell would substitute the name of the directory (for example, foo) for 
$directory and would pass that string (f00/*) to the tar program. The tar program would fail to 
identify any file named “” in that directory. When you type a command with a “x” at the shell prompt 
(or in an sh script), the shell automatically expands the x to the list of files. Under Tcl, this expansion 
is done by the g10b command. 

In the same way, if you try to group an argument to exec with single quotes, it will fail. The single 
quote has meaning to the UNIX shell interpreter (disable substitutions) but is just another character to 
the Tcl interpreter. 


The tclsh Shell Is Not COMMAND.COM 

This is the Windows equivalent of the previous mistake. Remember that the DIR, COPY, and DEL 
commands are part of COMMAND.COM, not standalone programs. You cannot get a directory within a 
Tcl script with a command such as the following. 


if Won’t work 
set filelist [exec dir C:*.*] 


There is no DIR.EXE, or DIR.COM for the Tcl shell to execute. The best solution is to use the Tcl 
glob, file copy, file delete, and file rename commands. If you really need the DIR output 
you can exec the COMMAND.COM program with the /C option. This option tells the COMMAND.COM 
program to evaluate the string after the /C as though it had been typed in at a command prompt. 


if This will get a list of files 
set filelist [glob C:/x.*] 
# This will get the output of the dir command 
set filelist [exec COMMAND.COM /C dir C:x*.x*] 


Note that fi 1elist will contain all the output from the DIR, not just a list of the files. 
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A Tcl List Is Passed as a Single Argument to a Procedure 
Notice the eval in the eval exec tar -cvf $archive $f11st line in the previous UNIX 
example. If you simply used 


if won’t work. 
exec tar -cvf $archive $fllst 


The content of f11st would be passed as a single argument to the exec command, which would 
pass them as a single argument to the tar program. Since there is no file named filel file2 


file3.., this results in an error. 
The eval command concatenates all of the arguments into one string and then evaluates that string. 
This changes the list from a single argument to as many arguments as there are file names in the list. 


df will work. 
eval exec tar -cvf $archive $fllst 


A new operator was introduced with Tcl 8.5. The {*} operator splits a list into its component parts. 
This is the preferred way to split a list into individual elements. Using the {*} operator limits expansions 
to the variable it’s associated with, avoiding potential errors when all the variables in a command string 
lose a level of grouping. 


df will work. 
exec tar -cvf $archive {*}$fllst 


Changing the Directory Is Done within a tclsh (or sh) Shell; It Is 
Not a Standalone Program 
The command exec cd $newDirectory is probably not what you want. 

The change directory command is a part of a shell. It changes the current directory within 
the shell. It is not an external program. Use the built-in Tc] command cd if you want to change the 
working directory for your script. 


Calculating the Time: Numbers in Tcl 


Numbers in Tcl can be represented in octal, decimal, or hexadecimal. The base of a number is deter- 
mined by the first (or first two) digits. If the first digit is not a 0, the number is interpreted as a decimal 
number. If the first digit is a 0 and the second character is x, the number is interpreted as a hexadecimal 
number. If the first digit is a 0 and the second digit is between 1 and 7, the number is interpreted as an 
octal number. If the first digit is a 0 and the second digit is 8 or 9, this is an error. 

In versions of Tcl without the clock command, it was common to split a time or date string and try 
to perform calculations on the parts of the time. This would work most of the time. Note that at 08:00 
the command 


set minutes Lexpr Llindex [split $time ":"] 0]*60] 


will generate an error, since 08 is not a valid octal number. If you need to convert a time/date to 
seconds in versions of Tcl more recent than 7.5, you should use the clock format and clock scan 
commands. 

If you need to process time and date in an older version of Tcl, or if you are reading data that may 
have leading zeros (the number of cents in a commercial transaction, for instance), use the string 
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trimleft command to remove the leading zeros. In the following example, note the test for an empty 
string. If the initial value is all zeros (000, for instance), the string trimleft command will remove 
all the zeros, leaving an empty string. An empty string will generate an error if you try to use it in a 
calculation. 


set value [getNumberWithLeadingZeros ] 
set value [string trimleft $value "0"] 
if {$value eq ""} {set value 0} 


19.3.3 set, lset, lappend, append, and incr Are the Only Tcl Commands 
That Modify an Argument 


The commands Ireplace, string, and expr all return a new value without modifying any original 
argument. 


if This WON’T remove the first list entry 
lreplace ist 00 "" 
if This WILL remove the first list entry 

set list [lreplace $list 00 ""] 

i## This WON’T shorten the string 

string range $myString 5 end 

if This WILL shorten the string 

set myString [string range $myString 5 end] 
i## This WON’T change the value of counter 
expr $counter + 1 
i## These commands WILL change the value of counter 
set counter [expr $counter + 1] 

incr counter} 


19.3.4 The incr Command Works Only with Integers 


Some commands (for example, commands that return locations and widths of objects on a canvas) 
return float values that incr will not handle. You can convert a floating-point number to an integer with 
the expr command’s roundQ and intQ functions, or you can use the expr command to increment 
a variable. Remember that you must reassign the new value to the variable when using the expr 
command. 


set variable [expr $variable + 1.0] 


19.3.5 The upvar Command Takes a Name, Not a Value 


When you invoke a procedure that uses the upvar command, you must pass the variable name, not 
$varName. 


proc useUpvar {variableName} { 
upvar $variableName localVariable 
set localVariable 0 

} 

## This will set the value of x to 0 

useUpvar x 
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if This will not change the value of x 
useUpvar $x 


6 Changes to Widgets Do Not Appear Until the Event Loop Is Processed 


If your wish script is making many modifications to the display within a procedure, you may need to 
add the update command to the looping. This will not only update the screen and show the progress 
but also scan for user input (such as someone clicking an abort button). This is discussed in detail in 
Chapter 11. 


Be Aware of Possible % Sign Reduction 


The bind and format commands both use the % as a marker for special characters. If you combine 
the two commands, the % will be substituted twice. For example, a bind command that should set a 
value when an entry field is entered might resemble the following. 


bind .entry <Enter> {set defaultVal [format %26.2f $value]} 


Note that there are two percent signs. When the cursor enters . entry, the script registered with the 
bind command will be evaluated. The first phase of this evaluation is to scan the script for % patterns 
and substitute the appropriate values. The %% pair will be replaced with a single %. When the script is 
evaluated, the format command resembles the following, which is a valid command. 


format %46.2f $value 


If only a single % had been used, it would have been discarded during the first evaluation, and the 
argument for the format command would have been simply 6. 2f. 


| CODING TIPS AND TECHNIQUES 


There are many ways to write a program. Some techniques work better with a particular language than 
others. The following describe techniques that work well with Tcl. 


19.4.1 Use the Interpreter to Parse Input 


Tcl is one of the very few languages that provide the script writer with access to a parse engine. This 
can save you time (and help you write more robust code) in several ways. 


Use Procedures Instead of switch Statements to Parse Input 
If you are accustomed to C programming, you are used to constructs such as the following. 


while {[gets stdin cmdLine]} { 
set cmd [lindex $cmdLine 0] 
switch $cmd { 
"cmdl"  {cmdlProcedure $cmdLine} 
"cmd2" {cmd2Procedure $cmdLine} 
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Whenever you add a new command using a switch statement, you need to add a new pattern to 
the switch command. In Tcl, you can write a loop to parse input such as the following. 


while {[gets stdin cmdLine]} { 
set cmd Llindex $cmdLine 0] 
set cmdName [format "%sProcedure" $cmd] 
i## Confirm that the command exists before trying to eval it. 


if {Linfo command $cmdName] != ""} { 
eval $cmdName $cmdLine 


} 


When the requirements change and you need to add a new command, you simply add a new 
procedure without changing the command parsing code. 


Use the info complete Command to Match Quotes, Braces, and Brackets 

The info complete command will return a | if a command is complete, and a 0 if there are opening 
quotes, braces, or brackets without the appropriate closing quotes, braces, or brackets. The info com- 
plete is designed to determine whether a Tcl command has unmatched quotes, braces, or brackets, 
but it can be used to test any line of text that may include nested braces, and so on. 


Use a Single Array for Global Variables 

Rather than use simple variables for global variables, group all shared variables a set of procedures 
will need in a single array variable. This technique reduces the possibility of variable name collisions 
when you merge sets of code and makes it easy to add new variables when necessary without requiring 
changes to the global commands in all procedures that will use the new value. 


Bad Style 


# Don’t use this technique 
proc initializeParameters { 
global height width linecolor 


set height 100 

set width 200 

set linecolor blue 
} 


Good Style 


i## Use this technique 
proc initializeParameters { 


global globalParams 

set globalParams(height) 100 

set globalParams(width) 200 

set globalParams(linecolor) blue 


756 CHAPTER 19 Tips and Techniques 


Better Style 


i## Use this technique 
proc initializeParameters { 


global globalParams 
array set globalParams { 
height 100 
width 200 
linecolor blue 
} 


Using a single associative array lets you save the program’s state with a single command, as in the 
following. 
puts $saveFile "array set myStateArray \ 
[list Larray get myStateArray ]]" 


This also lets you reload the settings with a simple source command. Saving the state in a data- 
driven loop allows you to add new indices to the state variable without needing to modify the save and 
restore state functions. 


Declare Globals in a Single Location 
If you use more than a few global variables, it can become difficult to keep all procedures that use them 
in sync as new variables are added. The names of the global variables can be kept in a single global 
list, and that list can be evaluated to set the global variables. 
set globalList terrorInfo errorCode argv argc \ 
stateArrayl stateArray2} 


proc someProcedure {args} { 
global globalList ; global {*}$globalList 
i## Perform processing. 

} 


Generate a GUI from Data, Not from Code 
Some parts of a GUI need to be generated from code, but others can be generated on the fly from lists. 
For example, a menu in which some items are optional can be generated with a set of commands such 
as the following. 
set cmdButton [menubutton .cmdButton \ 
-text "Select cmds" \ 
-menu .cmdButton.mnu] 
set cmdMenu [menu $cmdButton.mnu] 


if {LsupportedFeature One]} { 
$cmdMenu add command -label {Selection One} \ 
-command ProcOne 
} 
if {{[supportedFeature Two]} { 
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$cmdMenu add command -label {Selection Two} \ 
-command ProcTwo 


This menu could be generated with a loop and a list as shown in the next example. 
set cmdMenuList [list \ 

{Selection One} {procOne} \ 

{Selection Two} {procTwo} ] 


set cmdButton [menubutton .cmdButton -text "Select cmds" \ 
-menu .cmdButton.mnu] 


set cmdMenu [menu $cmdButton.mnu] 
foreach {label cmd} $cmdMenuList { 


if {Cselected feature $cmd]} { 
$cmdMenu add command -label $label -command $cmd 


The list-driven code is simpler to maintain, because the list of labels and commands is more tightly 
localized and the test need not be repeated. 

If the list can be generated at runtime from other data, it can reduce the amount of code that needs 
to be modified when the program needs to be changed as shown in the next code snippet that uses the 
contents of the 1iquidConversion to populate the menu. 


Oooo —_”———n— — aw» 
Example 9 


Script Example 


array set liquidConversion { 


liter 3.8 
quart 4 
{US gallon} 1 


{imperial gallon} 0.833 


set unitButton [menubutton .unitButton -text "Units" \ 
-menu .unitButton.mnu] 


set unitMenu [menu $unitButton.mnu] 


foreach nm [array names liquidConversion] { 
$unitMenu add command -label $nm \ 
-command "set globalConversion $liquidConversion($nm)" 
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The menu contents are defined by the contents of the 1iquidConversion array. When new 
conversion factors are added to the array, the GUI automatically displays the new selections. 


19.4.2 Handling Platform-Specific Code 


Tcl has excellent multiple platform support. In many circumstances you can use built-in Tcl commands 
that are identical across all platforms. However, sometimes there are spots where you need to write 
platform-specific code. For instance, in TclTutor, you can click on a word to get on-line help. Under 
UNIX, this is done using exec to run TkMan as a subprocess. Under Windows, the exec command 
invokes winh!p32.exe. 

The tcl_platform(platform) array variable (discussed in Chapter 5) contains the name of the 
platform where your code is being evaluated. Once you have determined the platform, there are several 
options for evaluating platform-specific code. 


e Place platform-specific scripts in a variable, and evaluate the content of the variable in the mainline 
code. This works well when the platform-specific script is short. 


switch $tcl_platform(platform) { 
"unix"  { 
set helpString "exec TkMan $topic" 


"win" { 
set helpString "exec winhlp32 -k$topic $helpFile" 


} 


if {LuserRequestsHelp]} {eval $helpString} 


e Place platform-specific code within tcl_platform(platform) test. If the platform-specific code 
is more complex, you may prefer to put a script within the test, as follows. 


if {LuserRequestsHelp]} { 
switch $tcl_platform(platform) { 
"unix"  { 
exec TkMan $topic 


win" { 
exec winhlp32 -k$topic $helpFile 


e If there are large amounts of platform-specific code, those scripts can be placed in separate files and 
loaded at runtime, as follows. 


# A platform-specific procedure named HelpProc is 
## defined in each of these script files. 
switch $tcl_platform(platform) { 
"unix" { 
source "unix_Procedures.tcl" 
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win" { 
source "win_Procedures.tcl" 


mac" { 
source "mac_Procedures.tcl" 
} 
} 
if {LuserRequestsHelp]} {tHelpProc} 


19.5 OPTIMIZATION 


The first question after “does it work?” is usually “can you make it run faster” The largest speed 
improvements come from either using a different algorithm or converting a section of Tcl script to 
compiled code. However, there are some techniques that will improve simple script performance. 

The first step at optimizing code is to understand which section of code needs to be optimized. In 
many cases the code that most obviously needs to be changed is not what’s slowing an application 
down. Two tools for analyzing speed are the profiler package and the time command. 

When updating code from one revision of Tcl to another it can be worthwhile to analyze subsets 
of the code. There has been a consistent effort at improving Tcl performance since Tcl 8.0. Some of 
these improvements have resulted from improving the behavior of individual commands and some 
have been implemented with new commands. 

The profiler package is part of Tcllib. It’s available at http://sourceforge.net/ 
projects/tcllib/ or it can be installed on your system with teacup if you are using an Act- 
iveState distribution. Profiler reports the number of times a procedure is invoked, the length of time a 
set of code spends in each procedure, how long it took to compile the procedure and a bit more. 

The profiler package supports being suspended and resumed to limit the report to a specific section 
of code and generates both human readable reports and machine readable lists. 

To use the profiler your code must: 


= 


. Load the profiler package with package require profiler 
Initialize the profiler with profiler::init 
3. Access the results with profiler::print or profiler::dump 


i 


The next example shows the profiler being used to compare two procedures that generate the same 
result when num is less than 10. 


—————————— eee eee 
Example 10 


Script Example 


package require profiler 


profiler::init 


760 CHAPTER 19 Tips and Techniques 


proc pl {num} { 
append num $num 
return [expr $num+1] 


proc p2 {num} { 
return Lexpr {$num*10+$num+1 } J 


for {set 1 0} {$i < 100} {incr i} { 
pl l 
p2 1 


puts Lprofiler::print] 


Script Output 


Profiling information for ::p1 


Total calls: 100 
Caller distribution: 
GLOBAL: 100 
Compile time: 1176 
Total runtime: 12367 
Average runtime: 123 
Runtime StDev: 110 
Runtime cov(%): 89.4 
Total descendant time: 0 
Average descendant time: 0 
Descendants: 
none 


Profiling information for ::p2 


Total calls: 100 
Caller distribution: 
GLOBAL: 100 
Compile time: 135 
Total runtime: 9052 
Average runtime: 90 
Runtime StDev: 19 
Runtime cov(%): 21.1 
Total descendant time: 0 
Average descendant time: 0 
Descendants: 
none 


Total calls: 0 


Profiling information for ::tcl::clock::format 


Total calls: 0 
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The time command is part of Tcl. It returns the length of time that it takes to evaluate a single 


command. The command might be a procedure call. 


Syntax: time script ?count? 


Returns the number of microseconds it takes to evaluate a script. 


script The script to evaluate. 


count An optional count of times to run the script and return the average. 


The next example demonstrates using time. Using the time command doesn’t require a list to 


collect average times. 


S$ $ i 


Example 11 
Script Example 
proc pl {num} { 
append num $num 
return CLexpr $numt+1] 


proc p2 {num} { 
return Lexpr {$num*10+$num+1 } J 


puts [time {pl 1} 1000] 
puts [time {p2 1} 1000] 


Script Output 
20.557 microseconds per iteration 
4.486 microseconds per iteration 
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19.6 TECHNIQUES FOR IMPROVING PERFORMANCE 


Use option command 

Tcl widgets can be customized when they are created with -option value. If you have a 
consistent set of options you are always using (perhaps a non-default font), it’s faster to use the 
option command (discussed in Chapter 14). 
Avoid shimmering 

A Tcl variable’s value is maintained internally in a Tc1_Obj as described in Chapter 15. The 
Tcl_Obj maintains two copies of the data, the string representation and the native representa- 
tion. When the value is accessed as a string the native representation is used to create a string 
representation and the native representation is cleared. When the value is accessed for a native- 
mode operation, the native representation is created from the string and the string representation is 
cleared. 

The value representation is converted in a “lazy” fashion. The conversion is only done when a 
command needs the representation that is currently cleared. 

Lists, numbers and dicts have a non-string native representation. If you can restrict accessing 
the values to a single type of operation, Tcl will not perform extra conversions. 


Code that shimmers 


proc pl {num} { 
## num is converted to a string. 
append num $num 
## num is converted to a number. 
return [Lexpr $num+1] 


proc shimmer {val} { 
# val is treated as a string to append the ".0", 
jf then converted to a number to divide it by 2. 
return [expr $val.0 / 2] 


} 


Code that does not shimmer 


proc p2 {num} { 
return Lexpr {$num*10+$num+1 } J 
} 


proc noShimmer {val} { 
return [Lexpr {double($val) / 2}] 
} 


Use most specific string commands for tests 

The string equal command is faster than string match which is faster than regexp. 
The pattern recognition code in string match and regexp is slower than the simple equal- 
ity comparisons in string equal. The eq and ne operators for the if command are as fast as 
string equal. 
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The string map command is much faster than regsub for the same reason. 
When the code requires patterns, you'll need to use regexp and regsub, but code that can use 
the simpler commands will run faster. 
e¢ Use in place commands instead of modify and assign 
Tcl 8.4 introduced the 1s et command to modify a list in place. Earlier versions of Tcl used set 
and |lreplace to create a new copy of a modified list. 


Syntax: lset ?indexList? value 
Modify a list by replacing the entire contents or a single list element with a 
new value. 


indexList A list describing the element to replace. If this is missing or an 
empty list, replace the entire list. If indexList is a list or a set of 
numbers the values represent indices with the first value being 
the index into the list and subsequent numbers being indices of 
sublist elements. 


value The new value to put in the list. 


In a trivial case, (shown in the example below) using ]1set takes about 2/3 the time of the 
equivalent set and 1 replace commands. 

For complex cases of replacing elements of internal lists, the ability to step into a list of lists 
and replace an individual element is much simpler than code to extract an element and replace it. 

Note that while 1set without an indexList and set each completely replace a list, they differ 
in that 1 set requires that the list already exist while set will create a new variable. 


——— een 
Example 12 
Script Example 


set Ist {a b c} 
puts “Start list $l1st" 


lset Ist B 
puts "After: lset Ist B" 
puts "$lst" 


set Ist {a b c} 


lset Ist B 
puts "After: lset Ist 1 B" 
puts "$lst" 


set Ist {a b c} 

set Ist [lreplace $lst 1 1 B] 

puts "After: set Ist \Clreplace $lst 1 1 B\]" 
puts " 


set Ist {a {b c} {d fe f} } } 
puts "\nStart list $lst" 
lset Ist B 
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puts "After: lset lst 1 B" 
puts st 


set Ist {a {b c} {d fe f} } } 
lset Ist 108 

puts "After: Iset Ist 1 0 B" 
puts st 


set Ist {a {b c} {d fe f} } } 
lset Ist {1 0} B 

puts "After: Iset Ist {1 0} B" 
puts St 


set Ist {a {b c} {d {e fF} } } 
lset Ist {2} D 

puts "After: Iset Ist {2} D" 
puts St 


set Ist {a {b c} {d {fe f} } } 
Iset Ist {2 0} D 

puts "After: Iset Ist {2 0} D" 
puts st 


set Ist {a {b c} {d {fe f} } } 
lset Ist {2 1 O} E 

puts "After: lset Ist {2 1 0} E" 
puts St 


Script Output 
Start list abc 
After: lset lst B 


B 

After: lset lst 1B 

aBece 

After: set lst [lreplace a B c 1 1 B] 
aBe 


Start list a {b c} {d {e f£} } 
After: lset lst 1B 

a B {d {e £} } 

After: lset lst 1 0B 

a {B c} {da {e £} } 

After: lset lst {1 0} B 

a {B c} {da {e £} } 

After: lset lst {2} D 

a {b c} D 
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After: lset lst {2 0} D 
a {b c} {D {e £}} 
After: lset lst {2 1 0} E 
a {b c} {d {E £}} 
| 


e Use 1assign to extract individual variables from a list 
It’s quite common for a script to receive data as a list of values and then need to deal with them 
individually. Traditionally this was done with a sequence of commands like this: 


set varO [Llindex $lst 0] 
set varl [Llindex $lst 1] 


When the foreach command was extended to support multiple loop variables it became pos- 
sible to replace code that had multiple calls to 1 index with a single foreach loop with a break 
command as the body. 

This was faster than multiple assignments in early releases of Tcl 8, and then became slower 
when the byte-code compiler was extended to compiling the contents of a loop. The compilation 
makes a loop run faster but when a loop is only evaluated once, the time for the optimization 
exceeds the time saved. Using foreach in the example below is actually slower than the three 
lindex calls. 

The 1assign command was added in Tcl 8.5 to optimize assigning elements of a list to a set of 
variables. It’s smaller and faster than the repeated set of set and 1 index commands and almost 
twice as fast as a foreach command. 

The next example shows three ways of extracting the values from a list. They each perform the 
same function. 
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Script Example 
set lst {liter 3.8 gallon} 


set startUnit Llindex $lst 0] 

set factor [lindex $lst 1] 

set endUnit [lindex $lst 2] 

foreach {startUnit factor endUnit} $lst {break;} 


lassign $lst startUnit factor endUnit 


puts "Multiply by $factor to \ 
convert from $startUnit to $endUnit" 


Script Output 


Multiply by 3.8 to convert from liter to gallon 
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e Use lists instead of arrays with numeric indices 
If you are familiar with C or FORTRAN type arrays you might be tempted to organize a set of 
values as an array with a numeric index and then use a for loop to access the elements. 
If your script will always access the data in a linear manner, use a list instead. 
The next example shows two procedures that return the sum of a set of numbers. The arraySum 
procedure accepts an array in which each value to add is assigned to an array with a numeric index. 
The second procedure accepts a set of values as a list. 
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Example 14 
Script Example 
proc arraySum {arrName} { 
upvar $arrName arr; 
set sum 0 
for {set 7 0} {$i < 1000} {incr 7} { 
set sum Lexpr {$sum + $arr($i)}] 
} 
return $sum 
} 
proc listSum {lst} { 
set sum 0 
foreach val $lst { 
set sum [expr {$sum + $val}] 
} 
return $sum 


for {set i 0} {$7 < 1000} {incr 7} { 
set valueArray($i) $i 
append valueList $i 


puts "Time to use array" 
puts [time {tarraySum valueArray} 10] 


puts "Time to use list" 
puts [time {listSum $valueList} 10] 


Script Output 
Time to use array 
2008.4 microseconds per iteration 
Time to use list 
1522.6 microseconds per iteration 
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e Place repeated code in a procedure or loop 
A script inside a loop or within a procedure is compiled to a byte-code the first time it’s encoun- 
tered. The compiled code is significantly faster than uncompiled code and the time for compiling is 
short. In most cases it’s a worthwhile trade-off. 


BOTTOM LINE 


This chapter has discussed several tricks, techniques, and tips for writing efficient and maintainable 
Tcl scripts. These include the following. 


e You can use other wish interpreters or new windows to debug a wish application. 

e Some applications should be written as separate programs, invoked with exec, rather than as 
extensions or Tcl scripts. 

e The Tcl interpreter is not the UNIX command shell or COMMAND. COM. 

e Be aware of possible leading zeros in numbers. 

e Most Tcl commands do not modify the content of their arguments. append, lappend, set, 
lset, and incr are exceptions. 

e Use the Tcl interpreter to parse data whenever possible, rather than writing new code to parse 
data. 

e Use a single global array for shared data instead of many variables. If you must use many variables, 
group them into a global list and evaluate that list to declare the globals in procedures. 

e Use data rather than code to control GUI contents whenever practical. 

e Use the profiler package or time command to analyze code before you try to optimize it. 
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# (number sign), 37, 38 

$ (dollar sign), 36, 40, 125 

% (percent sign), 22, 51, 754 

\ (backslash), 37, 41-43, 93-94, 125 
/ (forward slash), 93 

* (asterisk), 39, 42, 47, 125, 752 

; (semi-colon), 37 

{} (curly braces), 37, 38, 41-43, 755 
“ (quotes), 37, 38, 41-43, 755 

[] (square brackets), 36, 40, 47, 755 
? (question mark), 17, 47, 125 

& (ampersands), 71 

:: (double colon), 206, 232 

* (caret), 124 

: (colon), 169 

- (dash), 71, 76, 98 

. (period), 124 

| (pipe symbol), 102, 749 

+ (plus sign), 71, 125 
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acceptClient procedure, 642 
access option, 102 
acquire method, 312 
ActiveState, 1, 703-704 
ActiveState html man pages, 5 
after command, 383-385, 387, 640 
cancel, 385-386, 387 
script example/output, 384-385 
script registration, 110 
with sel f command, 306-308 
syntax, 383-384 
using, 250, 646-647 
aggregated objects, 312-315 
aggregation, 258-259 
all rows command, 168 
allrows subcommand, 164, 166 
alnum, 50, 128 
Alpha, 25 
alpha, 128 
alphabetic characters, 128 
alphanumeric characters, 128 
-anchor edge option, 346 
-anchor position, 396 
append command, 45, 753 
applications 
Critcl, 704, 727-728 


debug, 714-716 
FreeWrap, 704, 722 
frink, 705-709 
Komodo, 25, 704, 730-731 
MyrmecoX, 25, 704, 731-732 
naglefar, 704, 710-714 
Starkit, 704, 722-724 
SWIG, 704, 724-726, 727-728 
tclCheck, 704, 709-710 
TkTest, 704, 717-721 

apply method, 312 

arc item, 395 

arcosine, 72 

arcsin, 71 

arctangent, 72 

arctangent of ratio, 72 

arg arguments, 182 

argc variable, 136, 739 

args, 133, 182, 289 

arguments, 181-184, 289 
concatenation, 182 
default values, 182-184 
modifying, 753 
order, 183 
procedure, 181-184 
returns, 292 
script example/output, 182, 183 
too few, 13 
too many, 182 
variable number, 182 

argv variable, 136, 739 

array command 
get, 66 
names, 65-66 
set, 66, 98 

array operation, 737 

arrayName, 66, 66 

arrays 
access time, 176-177 
associated list values, 66 
associative, 65-67, 156-157, 168, 616-618 
indices, 66 
iterating through content of, 65 
name, 66 
value, 66 

ArraySum Procedure, 766 

ASCII strings, 68 

Association for Computing Machinery 

(ACM), 2 
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associative arrays, 65 
in caching references, 168 
commands, 65-67 
in defining structure, 616-618 
using, 156-157 
atime, 96 
atof, 575 
atol, 575 
atoms, 124 
number of occurrences, 125 
range, 124-125 
See also regular expressions 
author ID, 168 
auto_increment, 160 
auto_path global variable, 226 
awk, 6 


background color, 324 
bad strings, 46-47 
bar namespace, 206 
base classes, 299-301 
base64 namespace, 439 
Bash shell, 19, 22 
.bashrc onfiguration file, 19 
bat files 

program control, 8 

Tcl scripts vs., 7-8 

tclsh interpreter vs., 3 
baz, 206 
BeforeScript, 688, 694-695 
begintransaction subcommand, 164 
Bezier splines, 394 
binary command, 66 

format, 67-69 

scan, 67-69 
binary data, 66-68 
binary digits, 68 


bind command, 412-415, 447, 640, 647-648, 662 


bind subcommand, 415-418 
bitmap item, 396-397 

See also canvas items 
bitmap name, 396 
bitmapped conditional, 741-743 
bodN, 76 
body, 79, 133 
Boolean string, 45 
borderwidth width, 324 
bound variable, 681 
Bourne shel 1, 19, 22 
Brief, 25 


BrowseX web browser, 490 

button widget, 327 
creating, 329 
functionality, adding, 647-648 
options, 329 
script example/output, 329-330 
syntax, 387 

.buttonFrame, 337 

ButtonPress, 414 

ButtonRelease, 414 

BWidgets package, 667, 696-702 
LabelEntry command, 698 
language, 696 
notebook insert command, 697 
notebook raise command, 697 
NoteBook widget, 696-697 
primary site, 696 
script example/output, 697-702 
ScrolledWindow widget, 699-700 
supported platforms, 696 

byteOrder, 136 

bytes, 578 


C 
C array, 156-157 
C structs, saving data in, 154 
call stack, examining, 736-737 
cal] subcommand, 290 
callbacks 
html_library, 480-486 
registering methods for, 250-251 
TclOO, using with, 305-308 
canvas command, 392-393 
bind, 412-415 
coords, 399-401 
create bitmap, 397, 448 
create image, 397 
find, 403 
itemconfigure, 398-399 
lower, 403 
move, 401 
raise, 403-404 
canvas items 
arc, 395 
binding, 392, 412-415 
bitmap, 396-397 
coordinates, 392 
display coordinates, changing, 399-401 
displayable, creating, 394-398 
finding, 403-407 
fonts, 407-410 


identifiers, 391-392 
image, 397-398 
line, 394 
lowering, 403-407 
modifying, 398-399 
moving, 401-403 
oval, 395 
polygon, 395 
raising, 403-407 
rectangle, 395 
size, 410-412 
tags, 391-392 
text, 396, 407-410 
canvas widget, 327, 391-448, 450 
background color, 393 
bind command, 412-415 
bind subcommand, 415-418 
binding, 392 
closeenough distance, 393 
coordinates, 392 
creating, 392-393, 419-427 
focus, 418-419 
height, 393 
height size, 393 
help balloon, 427-436 
identifiers, 391-392 
image object, 436-447 
increment size, 393 
items, display coordinates, 399-401 
items, displayable, 394-398 
items, finding, 403-407 
items, lowering, 403-407 
items, modifying, 398-399 
items, moving, 401-403 
items, raising, 403-407 
scroll increment size, 393 
scrollregion bounding box, 393 
size, 393, 410-412 
tags, 391-392 
width, 393 
width size, 393 
canvasName command 
find, 447 
move, 447 
raise, 447 
cascade, 357 
catch command, 8, 40 
exception handling, 80-81 
next, 286 
cd command, 91 
cd newDir command, 112 
cget command, 325 
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chains, evaluating, 285-292 
changes file, 588 
channel handle, 70 
channel 1D, 100, 108 
channels 
closing, 104 
creating, 101-104 
character classes, 127-128 
checkbutton widget, 327, 354-355 
creating, 355 
name, 355 
script example/output, 355-356 
syntax, 355 
ChildInitScript, 688, 693-694 
chord, 395 
class command, 668 
script example/output, 668-670 
syntax, 668 
class methods, 252, 286 
class mixin methods, 286 
-class option, 511 
classes 
action upon, 278 
adding filter to, 269 
adding superclass to, 275 
base, 299-301 
changing, 280-282 
character, 127-128 
constructor, 277 
creating, 244-245, 263 
destructor, 277 
equivalence, 127-128 
mixing, 275-276 
modifying, 268-269, 277-278 
name, 275, 289 
using, 245 
assvar command, 308 
assvar procedure, 308-309 
lient socket, 104, 105-106 
ClientData, 572-574, 584 
clientData, 658 
clock format command, 752 
fe 
Cc 
e 
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ock scan command, 752 
ose command, 113 

ose subcommand, 164 

cmd command, 139, 748 
cmdName, 573 

cntrl, 128 

code checkers, 709-714 
nagelfar, 710-714 
tclCheck, 709-710 

See also programming tools 
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code formatter, 705-709 
coding tips/techniques, 754-761 
global variables, 755-756 
GUI generation, 756-758 
info complete command, 755 
interpreter use, 754-761 
parse input, 754-758 
platform-specific code, 758-759 
single array, 755-756 
collating elements, 127-128 
color selector widget, 497-498 
columnName, 161 
columns, 161 
columns subcommand, 164 
command shell, tcl sh as, 22-23 
commandArgs, 671 
COMMAND. COM program, 751 
commandName, 671 
command(s) 
associative arrays, 65-67 
deleting, 184-185 
evaluation, 43-44 
list processing, 55-61 
renaming, 184-185 
results, 39 
string processing, 47-54 
substitutions, 40-43 
See also specific commands 
comments, 38 
commit subcommand, 164 
compat directory, 589 
complex data, 616-626 
compound widgets. See megawidgets 
conditionals, 74-78 
if, 74-75 
switch, 75-78 
configure command, 170, 325-327 
conf igure procedure, 507 
configure subcommand, 164 
console command, 744 
constructor command, 242-243, 280 
constructor subcommand, 277 
constructors, 245—247 
container widgets, 336-344 
frame, 337-338 
label frame, 339-340 
panedwindow, 342-344 
ttk:notebook, 340-342 
contextHandle, 677 
conversion functions, 72-73 
coordinates, 392 
coords subcommand, 399-401 


COPY command, 751 
cosine, 71 
count modifier, 125—126 
create bitmap command, 397 
create image command, 397 
create subcommand, 244 
CREATE TABLE command, 160 
createStack command, 234 
createThread function, 659 
createUni que procedure, 218 
crimp extension, 2 
Critcl, 704, 727-728 
advantages of, 727 
critcl::cproc command, 727 
language, 727 
primary site, 727 
script example/output, 727-728 
supported platforms, 727 
critcl::cproc command, 727 
csh, 19 
-cshrc configuration file, 19 
ctime, 96 
Cygnus Solutions, 1 


D 

data 
complex, 616-626 
conversion, 575 
flow, controlling, 107-109 


keyed lists, manipulating with, 148-151 


manipulating, 164 
obtaining, 577-578 
ordered, manipulating, 146-148 
persistent data, 582-585 
representation, 38-39, 575-576 
saving in nested dict, 155 
shimmering, 576 

data types, 44-70 
associative arrays, 65 
binary data, 66-68 
handles, 70 
lists, 54-55 
strings, 45—47 

databases 


displaying returns as dicts and lists, 165-166 


introspection, 170-175 
dataList, 80 
db command, 165 
dbCmd command, 165, 168, 172 
db1Value, 578 
debug, 714-716 


debug 0 command, 715 
debug 1 command, 715 
language, 714 
primary site, 714 
script example, 716 
supported platform, 714 
debuggers, 714-717 
debug, 714-716 
graphic, 717 
See also programming tools 
debugging techniques, 733-767 
bitmapped conditional, 741-743 
command window, 744-747 
conditional puts, 741 
console window under Windows, 744 
error messages, reading, 733-734 
info level command, 736-737 
1 ist command, 734 
log files, generating, 735-739 
puts in printing value of variables, 741-743 
remote, 747-748 
script extraction for unit testing, 743 
scripts in interactive mode, 739-741 
second wish interpreter, 747-748 
tkcon session attachment, 743-744 
trace command, 737-739 
decimal digits, 128 
defaultBODY option, 76 
DEL command, 751 
delayButton widget, 420, 442-447 
deletemethod subcommand, 271, 273-274, 280 
delete_point command, 726 
demInit.c, 590, 593-595 
demo command, 589-590 
create, 590 
debug, 589 
get, 590 
set, 590 
demo extension, 590 
demInit.c, 590, 593-595 
DemoCmd.c, 590, 595-602 
demoDemo.c, 590, 602-616 
demoInt.h, 590, 591-593 
DemoCmd.c, 590, 595-602 
Demo_CreateCmd, 603-606 
demoDemo.c, 590, 602-616 
Demo_CreateCmd, 603-606 
Demo_DestroyCmd, 609-611 
Demo_GetCmd, 606-609 
Demo_InitHashTable, 602-603 
Demo_SetCmmd, 611-616 
Demo_DestroyCmd, 609-611 
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Demo_GetCmd, 606-609 
Demo_InitHashTable, 602-603 
demoInt.h, 590, 591-593 
description procedure, 644 
destroy method, 247 
destroy subcommand, 244 
destructor, 245-247 
class with, 245-247 
creating, 245 
returns, 292 
syntax, 246 
destructor command, 243, 280 
dev, 96 
dialog box, creating, 502-503 
dict, 682-683 
access time, 177 
adding elements to, 153 
displaying database returns as, 165-166 
file system as, 157-158 
nested, 155, 158-159 
script example/output, 151-152 
dict append command, 62-63 
dict command, 61, 98, 151-152, 165 
append, 62-63 
create, 61-62 
in grouping related values, 152-156 
replace, 63 
dictionaries, 61-64 
creating, 62 
modifying, 63-64 
nesting, 61 
replacing values in, 63 
digit, 50, 128 
DIR command, 751 
directories 
compat, 589 
default working, changing, 91 
doc, 589 
generic directory, 589 
mac, 589 
tests, 589 
unix, 589 
win, 589 
directory tree, 588-589 
subdirectories, 589 
top level files, 588 
See also extensions 
.displayFrame, 337 
doc directory, 589 
documentation, Tcl, 3-5 
double, 50 
DoWidgetCommand, 517 
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Doyle, Mike, 25 Tcl list and, 752 
Draw procedure, 524 tclsh shell and, 751-752 
drink method, 312 zip archive, creating, 750 
.dtprofile configuration file, 19 executable script, 137-138 
Dynamic Link Library (DLL), 586 execute subcommand, 169 
execution speed, 140 
expand boolean option, 346 
E expect command 
eagle implementation, 9 expect, 670, 671-672 
Eclipse, 25, 703 exp_send, 670, 673 
element command, 368 spawn, 670-671 
elements expect extension, 1, 2, 666, 670-675 
adding, 153 commands, 670 
collating, 127-128 language, 670 
inserting into lists, 59 primary site, 670 
Emacs, 25, 703, 743 script example/output, 672-675 
End-Of-File, 100, 107 supported platforms, 670 
endIndex, 467-468 syntax, 670-671 
ensembles, 222-225 exponential functions, 72 
entry widget, 327, 330-333 export command, 271, 280 
creating, 330 expr command, 6, 43 
syntax, 387 int, 753 
entryForm widget, 561-563 math expression, 71 
.entryFrame, 337 round, 753 
env variable, 136 expression, 130 
eof command, 107, 113 exp_send command, 670, 673 
equivalence classes, 127-128 extension generators, 724-728 
errCodePtr, 609 Critcl, 727-728 
error command, 8, 83 SWIG, 724-726 
error messages, reading, 733-734 extensions, | 
errorCode variable, 80-83, 136 accepting data from interpreter, 574-575 
errorInfo, 80-83, 136, 611 building, 586-589 
errors, 40 BWidgets, 667 
catch command, 40 complex data, 616-626 
improper installation, 19 converting Tcl data to C data, 575 
eval command, 188-190 data representation, 575-576 
event definition, 414-415 directory tree, 588-589 
event loop, 382-383, 640-651 expect, 666, 670-675 
after command, 640, 646-647 file names, 587-588 
bind command, 640, 647-648 function name, 586-587 
fi leevent command, 640-644 functional view, 572-585 
interpreter, 648-651 graphic, 702 
script example/output, 383 Img, 667, 702 
trace command, 640, 644-646 [incr Tcl], 12, 666, 667-670 
widget changes and, 754 initialization function, 572, 586-587 
EventType, 545 naming conventions, 586-589 
exact option, 76 obtaining data, 577-578 
exception handling, 8, 80-83 OraTcl, 12 
exec command, 93, 748-749 overview, 572 
problems with, 751-752 persistent data, 582-586 
syntax, 749 registering commands with interpreter, 


tar achive, creating, 749-750 573-574 
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returning status to script, 581-582 file names, 587-588 

returns, 578-581 file systems 

structural overview, 586 as dict, 157-158 

SybTcl, 12 file paths, 93-95 

TclX, 12, 666, 675-679 items, properties of, 96-98 

use considerations, 665-666 navigating, 91-93 
extent angle, 395 fileDict procedure, 676 
external, 248 fileevent command, 113, 640-644, 662 
extFoo_Cmd, 587 with multiple clients, 642-644 
ExtName AppInit, 587 script registration, 108-109 
extName.c file, 587 using, 640-642 
extNameCFM68K.sh] file, 588 filelist, 751 
extNameCmdAL.c file, 587 fileName argument, 102, 749 
extNameCmd.c file, 587 files 
extNameCmdMZ.c file, 587 existence, 96 
extNameCommand.c file, 588 in packages, 226 
extNameCommand_Cmd, 587 permissions, 102 
extName.d11 file, 588 read and write access, 102 
extName.h file, 587 read-only access, 102 
ExtName_Init, 586-589 removing, 98-99 
extNamelInt.c file, 587 statistics, 96-97 
extNamelInt.h file, 587 type, 96 
extName.1ib file, 588 write-only access, 102 
extName.shlb file, 588 Fill color, 394, 396 
extName.s1 file, 588 fill direction option, 346 
extName. so file, 588 filter command, 243-244, 260, 269, 273-274, 

280 
filter methods, 243, 252, 263, 285 

F FilteredLB widget, 533, 541, 570 
fconfigure command, 107-109, 113 filters, 260-263, 269 
field justification, 51 FindItem method, 312 
field width, 51 findURL procedure, 134-135 
file association First, 59 

Windows 7, 28-32 flags parameter, 596, 612, 614, 658 

Windows Vista, 28-32 Flist, 752 

Windows XP, 27-28 float, 72-73 
file attributes command, 98 floating point remainder, 72 
file browser widget, 498-500 flush command, 108 
file command, 93-94 focus, 418-419 

attributes, 112, 113 font command 

copy, 751 actual, 408, 447 

dirname, 113 families, 408, 447 

exist, 112 measure, 408, 447 

join, 95, 112 font fontDescriptor, 396 

nativename, 94 fonts, 407-410 

normalize, 94 descriptor, 324 

rename, 751 family, 408 

rootname, 113 size, 408 

split, 95, 112 style, 408 

stat, 112 f00 command, 587 

tail, 113 for command, 78-79, 118-120 


type, 112 for loop, 8, 118-120, 140, 766 
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force, 210 
foreach command, 79-80 
data manipulation, 164 
inserting/deleting text, 458 
multiple loop variables, 765 
SQL command and, 168 
using, 121 
foreach loop, 121, 140, 765 
foreach subcommand, 164, 166 
foreground color, 324 
foreignkeys subcommand, 164, 173 
format command, 165, 168 
binary, 67-69 
script example/output, 54-55 
string processing, 47, 50-52 
formatDefinition, 51 
formatString, 52 
for_recursive_glob command, 676 
forward subcommand, 270, 273-274, 280 
fossil, 633-634 
frame widget, 328, 336, 337-338 
background color, 337 
border width, 337 
creating, 337 
height, 337 
options, 337 
relief for, 337 
script example/output, 337-338 
syntax, 337, 387 
width, 337 
FreeBSD, 1 
freeProc, 579 
FreeWrap, 704, 722 
language, 722 
primary site, 722 
supported platforms, 722 
zip file feature, 722 
frink, 704, 705-709 
command line options support, 705-707 
compiling (MS Windows), 707 
distribution, 707 
language, 705 
primary site, 705 
for syntax checking, 708 
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General Electric, 12 

generic directory, 589 
geometry manager, 322, 336 
geometry string, 429 

get method, 668 


getName method, 312 
getNext namespace, 218 
gets command, 100, 110, 113, 641 
getUni que procedure, 212-214 
gid, 96 
GIF images, 443 
glob command, 92-93, 112, 751 
glob option, 76 
global command, 135, 191, 195, 212 
global scope, 191-197 
global variables, 135 

declaring, 135 

information, 136-137 

single array for, 755-756 

in single location, 756 
glue language, 6 

script use, 6 

Tcl as, 6 
go command, 644 
grab command, 543-544 
grab current command, 567 
grab status command, 567 
graph, 128 
graphic debuggers, 717 
graphic extensions, 702 
graphic handle, 70 
graphics, 321-387 
basic widgets, 327-328 
button widget, 329-330 
checkbutton widget, 354-355 
color naming convention, 323 
container widgets, 336-344 
dimension conventions, 323-324 
entry widget, 330-333 
frame widget, 337-338 
grid layout manager, 351-352 
label widget, 328-329 
label frame widget, 339-340 
listbox widget, 367-371 
menu widget, 356-357 
namespace in, 333-335 
options, 324-325 
options, setting, 325-327 
pack layout manager, 346-351 
panedwindow widget, 342-344 
place layout manager, 344-346 
radiobutton widget, 353-354 
selection widgets, 352-371 
TclOO in, 335-336 
ttk:notebook widget, 340-342 
widget layout, 344-352 
widget naming conventions, 322-323 
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widgets, creating, 322-323 syntax, 481 
greedy behavior, 127 using, 478 
grid command, 24, 322, 336 http handle, 70 
grid layout manager, 351-352 hyperbolic cosine, 72 
column number, 351 hyperbolic sin, 72 
columnspan number, 351 hyperbolic tangent, 72 
options, 351 hypertext links, 480-486, 491 
row number, 351 hypotenuse, 72 
rowspan number, 351 
script example/output, 351-352 
syntax, 351 I 
GUI 1/O channels, 23 
generating, 756-758 identifiers, 391-392 
Tk, 6 idletasks, 382 
GUI-based programming, 13 idPtr, 658 
if command, 8, 74-75 
if/else,8 
H image command, 437-438 
handles, 70 create, 437-438 
channel, 70 create bitmap, 438-439, 447, 448 
graphic, 70 create photo, 439-442, 447 
http, 70 delete, 437, 447 
hash tables, 582-585 height, 447 
creating, 584-585 identifier handle returned by, 397 
data, retrieving, 584-585 names, 437-438, 448 
data, setting value of, 584 type, 447 
entries, adding, 584-585 width, 447 
entries, creating, 583 image item, 397-398 
entries, deleting, 583 image objects, 436-447 
entries, finding, 583 creating, 437 
initializing, 583 deleting, 437 
keys, 583 names, retrieving list of, 437-438 
pointer, 583, 584 imageName command, 453 
hashkeyPtr, 606 cget, 440 
heartBeat command, 647 configure, 440 
height number, 324 copy, 448 
help balloons, 427-436 get, 448 
hexadecimal digits, 68, 128 put, 448 
highlightbackground color, 324 images 
HMgot_image, 480, 491 bitmap, 438-439 
HM1ink_callback, 483-485, 491 GIF, 443 
HMset_image, 480-481, 491 oading, 480-486 
Hobbs, John, 23 photo, 439-442 
HPUX, | text widget, 455, 474-478 
HTML, 478 Img extension, 2, 667 
HTML text, displaying, 478-480 anguage, 702 
htm117b parsing engine, 478 ibraries, 702 
html_library, 478 primary site, 702 
callbacks, using, 480-486 supported platforms, 702 
interactive help with, 486-490 incr command, 73-74, 753 
script example/output, 479-480, 482-483, 484-486, [incr Tcl] extension, 1, 241, 666, 667-670 


488-489 class definitions, 667 
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[incr Tcl] extension (continued) 
class method definition, 668 
contact, 667 
help files, 668 
language, 667 
mailing list, 667 


nam 


espace command, 667 


primary site, 667 
supported platforms, 667 
supports, 10 

index, 66, 358, 368 


indexL 
indexP 
info c 
info c 
ca 
con 
de 
des 
fi 


1St; 763 

tr, 596 

ass, 285 

ass command, 267, 317 
, 290 

structor, 292 


Finition, 292, 296 


ructor, 292 
ers, 293 


forward, 293, 296 
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me 
me 
mix 
sub 
sup 


ances, 302 

hods, 292 

hodtype, 292, 295 

ins, 298, 300-301 
classes, 298, 299, 301-302 
erclasses, 298 


info command, 85-86, 285 


arg 


s, 186-187 


commands, 236 


com 
lev 
info o 
cal 
ins 
mix 
nam 
synt: 
var 


plete, 755 

el, 197, 736-737, 741 
bject command, 267, 317 
1, 290 

tances, 304 

ins, 298, 300-301 
espace, 303 

ax, 285 

s, 303 


information variables, 136-137 
inheritance, 251-260 
adding superclass, 275 
aggregation, 258-259 
examining, 298-299 
method chaining, 252 
mixins, 256-257 
modifying, 275-276 
multiple, 255-260 
single, 253-255 


init.t 
ino, 97 


cl, 19, 226 


input, 100 


installing 
errors when, 19 
Rivet, 686-687 
Tcl/Tk, 635 
tclsh interpreter, 17-18 
wish interpreter, 17-18 
integer, 50, 160 


integrated development environments (IDEs), 25, 


728-732 
Komodo, 730-731 
KomodoEdit, 729-730 
MyrmecoX, 731-732 
See also programming tools 
internal, 248 
interp command, 595, 748 
create, 648, 662 
eval, 650-651, 662 
transfer, 649-651, 662 
interpreter(s), 662 
data acceptance from, 574-578 
data conversion, 575 
data, obtaining, 577-578 
data representation, 575-576 
embeddable, 11-12 
embedded, 657-662 
embedding, 626-633 
event loop, 648-651 
extensibility, 9 
extensible, 11 
general-purpose, 8-11 
J/O implementation, 9 
multi-platform, 8 
multiple, 648 
parse input, 754-758 
persistent data, 582-585 
power, 8 
Python, 10 
registering new commands with, 
573-574 
returning results, 578-581 


returning status to script, 581-582 


safe, 648 

slave, 648-649 

speed, 8 

string manipulation, 9 

supported platforms, 8 
intValue, 578 
invokeCommand2, 421 
IP address, 112 


itemconfi gure command, 398-399 


iterations, 139 
Ixia test equipment, 12 
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J line item, 394 
Java, Tcl/Tk vs., 10-11 linsert command, 59 
join command, 56-57, 146 list, 59, 79 
joinable thread, 653, 655 list command, 55, 734 
JPEG library code, 702 example, 60-61 
justify style, 396 join, 56-57 
append command, 55-56 

K index, 58-59 

y insert, 59 
keyed lists, 148-151 length, 57 


KeyPress, 414 

KeyRelease, 414 

keyType, 583 

Komodo IDE, 25, 704, 730-731 
language, 730 
mean procedure, 730 
primary site, 730 
supported platforms, 730 

Komodokdit IDE, 25, 728-730 
completion hints, 730 
language, 729 
primary site, 729 
supported platforms, 729 
syntax reminders, 730 
template, 729 

Korn shel], 19, 22 


L 


label command, 24 
label widget, 327 

creating, 328 

options, 328 

script example/output, 328-329 
labelEntry class, 564 
LabelEntry megawidget, 511-512 
LabelEntry widget, 698 
label frame widget, 328, 336, 339-340 

background color, 339 

creating, 339 

label anchor location, 339 


replace, 59-60 
search, 57-58 
split, 56 


listbox curselection command, 513 
listbox widget, 327, 367-371 


creating, 367-368 

elements, inserting, 368 

elements, selecting, 369-370 

empty, 368 

entries, deleting, 369 

entries, multiple, 367 

entries, selecting, 367-368 

index, 368 

script example/output, 368-371 
scrollbar widget with, 372, 376-379 


lists, 54-55 


access time, 176 

of base classes, 299-301 

conversion to string, 56 

displaying database returns as, 165-166 
examining with for loop, 118-120 
extracting elements from, 58-59 
invalid, 55 

joining elements into string, 147 

keyed, 148-151 

for ordered data manipulation, 146-148 
performance improvement with, 766 
processing commands, 55-61 

splitting, 42-43 

string conversion to, 117-118 


script example/output, 339-340 valid, 55 
syntax, 339 listVar, 79 
text, 339 11length command, 57 
append command, 55-56, 753 load command, 748 
assign command, 146, 765 local scope, 191-197 
ast, 59 log base 10, 72 
legitimate strings, 46 .|ogin configuration file, 19 
ength, 578 lookup associative array, 168 
Libes, Don, 704, 714-716 looping, 78-80 
ibrary, 589 for command, 78-79, 118-120 
icense file, 588 foreach command, 79-80 
index command, 58-59, 146, 765 while command, 79 


780 = ‘Index 
loops, repeated codes in, 767 tk_getSaveFile, 500 
ower, 50, 128 tk_messageBox, 501-502 
lowercase letters, 128 tk_optionMenu, 496 
replace command, 59-60, 146-147, 763 tk_popup, 503-506 
search command, 57-58 menu widget, 327, 356-364 
performance, 175 creating, 357 
using, 122-124 entries, deleting, 359-360 
set command, 753, 763 index, 358, 360 
sort, 145 options, 357 
script example/output, 358, 359, 360-364 
M subcommands, 357-358 
mac directory, 589 syntax, 357, 359 
machine, 136 menubars, 365-367 
Macintosh menubutton widget, 327, 356-364 
editors, 25 creating, 356 
exiting tclhs/wish, 19 hot key position, 356 
init.tcl location, 226 menu widget associated with, 356 
man page, 5 script example/output, 358-364 
menubar, 365-366 syntax, 387 
starting tc] sh/wish under, 20-21 text, 356 
Tcl script file evaluation on, 32-33 tk_optionMenu, 496 
Tcl/Tk installation, 635 message widget, 327 
MacWrite, 25 method command, 242, 280 
makeInteracti onWindow procedure, 745 methods, 247-251 
MakeScrolledLB procedure, 515-516 adding to objects, 284 
MANPATH environment variable, 3—5 chaining, 252, 284 
markID, 452 creating, 269 
marks, text widget, 452, 454 defining, 247-248 
math operations, 70-74 deleting, 271 
megawidgets, 321, 495-568 evaluating, 248-250 
access time, 507 examining, 292-298 
building, 511-512, 545 exported, 272 
building philosophy, 506-509 forwarding, 270 
-class option, 511 invoking from within, 248 
configuration, 507-508 modifying, 269-274 
construction automation, 550-567 names, 272 
display in application window, 506 naming rules, 247 
frames, 507 registering for callbacks, 250-251 
in megawidgets, 533-542 renaming, 270-271 
modal, creating, 542-549, 568 returns, 292 
modal operation, 507 static, 278-279, 310-312 
modeless operation, 507 unexported, 272 
multiple language, creating, 524-533 using, 247-248 
option command and, 510-511 methodtype subcommand, 290 
rename command and, 509 Microsoft Windows 
scrolling 1istbox, 512-522 editors, 25 
standard dialog, 495-506 exiting tclhs/wish, 19 
subwidget access, 508 file association, Vista and 7, 28-32 
TclOO, 550-567, 568 file association, XP, 28-32 
tk_chooseColor, 497-498 init.tcl location, 226 
tk_dialog, 502-503 menubar, 365-366 


tk_getOpenFi le, 498-500 starting tcl sh/wish under, 19-20 


Tcl help, 3-4 
Tcl help, accessing, 3-4 
Tcl script file evaluation under, 27-32 
Tcl/Tk installation, 635 
zip archive, creating, 750 
Microsoft Word, 25 
millisecond, 383 
mimencode, 439 
mistakes, 751-754 
argument modification, 753 
exec command, 751-752 
incr command, 753 
% sign reduction, 754 
time calculation, 752-753 
upvar command, 753-754 
widget changes, 754 
MIT Otcl, 241 
mixin filter, 262—263 
mixin methods, 252 
mixin subcommand, 280, 283 
mixins, 256-257 
per-object, defining, 283-284 
returns, 298 
mmencode, 439 
mode, 97 
modifier, 413 
modularization, 83-86 
code from script file, 84-85 
procedures, 84 
Tcl interpreter state, 85-86 
modules, 205, 230-231, 237 
move procedure, 196 
move subcommand, 401 
msg, 595 
mtime, 96 
multiple inheritance, 255-260 
Multipurpose Internet Mail Extensions (MIME), 439 
my command, 560 
my varname command, 307-308, 318, 335 
myapp.tcl file, 18 
MyrmecoX IDE, 25, 704, 731-732 
language, 731 
package knowledge, 731-732 
primary site, 731 
supported platforms, 731 
MySQL, 12, 159 
mysqlDB command, 163 


naglefar, 704, 710-714 
command, 710-711 
language, 710 


primary site, 710 


script examples/output, 711-714 


supported platforms, 710 
namespace command, 205, 421 

children, 208, 211, 237 

code, 333-334, 523-524, 567 
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current, 208, 222, 232, 250, 309, 333, 523-524, 567 


ensemble, 222-225, 237 
eval, 208-209, 212, 231, 236 


export, 208, 209-210, 236, 236 


import, 208, 210, 237 
[incr Tcl] extension, 667 
inscope, 523 
scope, 208 
variable, 243 
namespacelD, 211 
namespaces, 206 
aggregating, 219 
creating, 212-214 
ensembles, 222-225 
entities, accessing, 208 
exporting procedures, 209-210 
global scope, 206, 215 
identifiers, 206, 208, 232 
importing procedures, 210-211 
local scope, 206 
naming rules, 206-207 
nesting, 215-221 
packages and, 231-233 
populating, 212-214 
reason to use, 208 
returns, 211 
scope, 206 
stack, 234-236 
unique features, 206 
widgets and, 333-335 
nativename, 94 
natural log, 72 
Neatware, 703-704 
nested dict, 155, 158-159 
NetBeans, 703 
netWorth method, 259 
new subcommand, 244 
newDirectory, 91 
<newline>, 37 
newline character, 749 
next argument, 119-120 


next command, 243-244, 252, 263, 269, 286, 289, 568 


nextto command, 289, 317 
nlink, 97 

normalize, 94 

not null, 160 
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notebook raise command, 697 
NoteBook widget, 696-697 
Notepad, 25 

Noumena Corporation, 1, 117 
numberArg, 183 


0 


object methods, 285 
object mixin methods, 285 
object-oriented programming, 2, 197, 241-242 
callbacks, using with, 305-308 
class, 242-247 
class modification, 268-274, 277-278 
constructor modification, 277—278 
destructor, 245-247 
destructor modification, 277-278 
filters, 260-263 
functionalities, 308-317 
inheritance, 251—260 
inheritance modification, 275-276 
methods, 247-251 
object modification, 280-284 
static methods, 278-279, 310-312 
static variables, 278-279, 308-310 
variable modification, 277-278 
widget and, 335-336 
objects, 197-200, 317 
adding method to, 284 
aggregated, 312-315 
changing behavior of, 315-317 
changing class of, 280-282 
creating, 278 
examining, 301-305 
growing/changing, 315-317 
mixins, 283-284 
modifying, 280-284 
script example/output, 197-199 
ODBC, 159 
00::¢lass command, 268 
create, 242, 277, 284, 296, 302 
overview, 242 
oo::def ine command, 267, 268, 280, 317 
oo::def ine namespace, 310 
oo::Helpers namespace, 310 
oo::objdefine command, 267, 280, 315 
open command, 101, 113 
optimization, 759-761 
option command, 762 
add, 510, 567 
megawidgets and, 510-511 
Oracle, 159 
OraTcl extensions, 12 


0s, 137 

osVersion, 136 

Ousterhout, John, 2 

outline color, 394 

output, 99 

oval item, 395 

overrideredirect command, 430 


P 
pack command, 322, 336, 346-351 
pack layout manager, 346-351 
options, 346-347 
script example/output, 347-350 
syntax, 346 
package command, 205, 225 
provide, 225, 227-228, 230, 237 
require, 228, 233, 237 
version numbers, 228-229 
packages, 225-233 
absolute name, 231 
arbitrary, package creation in, 232 
creating, 229 
files/variables within, 226 
name, 227, 228 
namespaces and, 231-233 
Rivet, 667, 686-696 
stack, 234-236 
using, 229-230 
version number, 227, 228-229 
packaging tools, 721-724 
freewrap, 722 
Starkit, 722-724 
Starpack, 722-724 
See also programming tools 
padx number, 324, 347 
pady number, 324, 347 
panedwindow widget, 328, 336, 342-344 
creating, 343 
script example/output, 343-344 
syntax, 343 
pathName, 97 
patN option, 76 
pattern, 172, 210, 211 
performance improvement, 762-767 
lists, using, 766 
option command, using, 762 
in place commands, using, 763 
repeated codes in procedure or loops, 767 
shimmering, avoiding, 762 
string commands for tests, 762-763 
Perl, Tcl/Tk vs., 9-10 
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permissions argument, 102 parse input, 754-755 
perPage.tcl, 688 proc command, 133-134 
perProcess.tcl, 688 renaming, 184-185 
photo images, 439-442 repeated codes in, 767 
pico, 25 string evaluation, 188-190 
pieslice, 395 string substitution, 187-188 
pkgIndex.tcl file, 226, 227-228, 229 variable scope, 135-136 
pkg_mk Index command, 227, 229, 237 processData procedure, 184 
place command, 322, 336, 344-345 -profile configuration file, 19 
place layout manager, 344-346 profiler package, 759 

script example/output, 345-346 programming tools, 703-732 

syntax, 345 code checkers, 709-714 
platform, 136 code formatter, 705-709 
platform namespace, 214 debuggers, 714-717 
platform-specific code, 758-759 exercising/regression testing, 717-721 
PNG library code, 702 extension generators, 724-728 
pointerSize, 137 integrated development environments, 728-732 
pointHandle, 726 packaging tools, 721-724 
polygon item, 395 See also applications 
pop method, 244 protocol command, 431 
pop-up menu window, creating, 503-506 pull-down menus, 356-367 
ports, 104-105 push method, 244 
position field, 59, 452 puts 
positivelnteger, 583 conditional, 741 
Post Office Protocol (POP), 105 in printing value of variables, 741-743 
Postgres, 159 puts command, 23-24, 35, 99, 113 
power, 72 pwd command, 91, 112 
prepare command, 169 
prepare subcommand, 164, 168 R 
preparecal] subcommand, 164 radiobutton widget, 327, 353-354 
primary key, 160 creating, 353 
primarykeys command, 173 name, 353 
primarykeys subcommand, 164 options, 353 
proc command, 84, 133, 184, 242 script example/output, 353-354 
procedure arguments, 181-184 syntax, 353 

concatenation, 182 random numbers, 73 

default values, 182-184 read command, 100-101, 113 

order, 183 read operation, 737 

procedure, 181-184 readable events, 110 

too few, 183 readData procedure, 642 

too many, 182 readLine procedure, 110 

variable number, 182 README file, 588 
procedures, 84, 184 record, 152 

arguments, 181-184 rectangle class, 260 

creating, 133-137 rectangle item, 395 

deleting, 184-185 referenced tables, 167-175 

findURL, 134-135 references 

findUrl, 134-135 caching, 168 

global information variables, 136-137 inserting rows with, 167 

global variables, 136-137 regexp command, 76, 124, 762 

information about, 185-187 in evaluating string, 189 


keyed pair list, 148-151 in searching string, 131-132 
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regexp command (continued) 
in searching text, 131-132 
regexpArgs variable, 189 
regsub command, 128 
regular expressions, 124-133 
advanced/extended, 126-131 
atoms, 124-125 
basic, 124-126 
character classes, 127—128 
collating elements, 127-128 
commands implementing, 128-131 
count modifier, 125—126 
equivalence classes, 127-128 
examples of, 126 
greedy behavior, 127 
implementing, 128-131 
internationalization, 127 
matching rules, 124-126 
minimum/maximum match, 127 
non-ASCII values, 127 
relief, 324 
remote debugging, 747-748 
rename command, 184 
megawidgets and, 509 
syntax, 567 
renamemethod subcommand, 280 
replace command, 763 
resultsets subcommand, 164 
returnCharPtr, 609 
returnObjPtr, 609 
returnStructPtr, 606 
Rivet, 667, 686-696 
authors, 686 
BeforeScript, 688, 694-695 
ChildInitScript, 688, 693-694 
form creation, 689-691 
installing, 686-687 
language, 686 
mailing list, 686 
perPage.tcl, 688 
perProcess.tcl, 688 
primary site, 686 
purpose, 686 
script example/output, 691-693 
supported platforms, 686 
rollback subcommand, 164 
rows, 161, 167 
rules, 124 
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safe interpreter, 648 
Sarachan, Baron, 12 


scale widget, 328, 379-381 
creating, 379-380 
label, 380 
naming, 379 
options, 379 
orientation, 379 
resolution, 380 
script example/output, 380-381 
scrollbar widget vs., 379 
size, 379 
syntax, 387 
scan command, 47 
format string of, 52-53 
scan subcommand, 67 
scanfile command, 677 
scanmatch command, 677 
scheduleCommand2, 420 
Schroeder, Hattie, 25 
scope 
global, 191-197 
local, 191-197 
namespace, 206, 206 
scripts, 7, 24 
canceling, 385-386 
control structures, 8 
error handling, 7 
evaluating, 25-26 
evaluating, Macintosh, 28-32 
evaluating, UNIX, 26-27 
evaluating, Windows, 27-32 
executable, 137-138 
extraction for unit testing, 743 
GUI support, 7, 8 
interactive evaluation, 23-24 
interactive mode debugging, 739-741 
language consistency, 7 
loading code from, 84-85 
making, 137-138 
math operations, 8 
MS-DOS .bat files vs., 7-8 
program output access, 8 
program output handling, 7 
returning status to, 581-582 
scheduling, 383-385 
string manipulation, 8 
Unix shell scripts vs., 7 


scrollbar commands, intercepting, 376-379 


scrollbar widget, 328, 372-379 
creating, 372 
details, 373-374 
interaction, 372 
listbox widget with, 372, 376-379 


scale widget vs., 379 
slider size/location, 374 
scrolledLB command, 512-514, 551 
delete, 513 
insert, 513 
selection, 513 
subwidget, 514 
widgetcget, 513 
widgetconfigure, 513 
scrolledLB procedure, 551 
configuration options, 512 
configuration values, 512 
return, 512 
scrolledLBState variable, 515 
scrolledLB widget, 512-514 
code, 517-522 
creating, 512 
implementing, 515-516 
subwidgets, 516 
using, 514-515 
scrolledLBState variable, 515 
ScrolledWindow widget, 699-700 
sdx program, 722-723 
searchSpec, 404 
sed, 6 
selection widgets, 352-371 
checkbutton, 354-355 
listbox, 367-371 
menu, 356-357 
radiobutton, 353-354 
self class command, 308-309, 318 
self command, 278 
after command with, 306-308 
callback linking, 308 
creating callbacks, 306-308 
method registration, 250, 335, 568 
object, 306 
returns, 560 
separator, 357 
server socket, 104, 109-112 
set command, 39 
arguments, modifying, 753 
lists, splitting, 42 
lset command vs., 763 
string substitution, 187-188 
variable value definition, 44 
sh shell, 752 
shimmering, 575-576, 762 
shortenText procedure, 385 
shortTest.tcl script, 718-719 
show method, 247 
showArgs procedure, 182 
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showCal1 method, 261 
showDefaults procedure, 183 
showString, 655 
showValue, 248 
side side option, 346 
sin, 71 
single array, 755-756 
single inheritance, 253-255 
single selection, 367 
slave interpreter, 648-649, 662 
Smartbits, 12 
SNIT, 241 
socket command, 101, 113 
server-side, 109 
syntax, 104 
sockets, 104—112 
address, 104 
client, 105-106 
data flow control, 107-109 
host, 104 
opening, 104-105 
ports, 104-105 
server, 109-112 
types of, 104 
Software Change Request, 315 
Software System Award, 2 
Solaris, 1 
source command, 84-85 
space, 50, 128 
spawn command, 670-671 
speed, 139-140 
spinbox widget, 328 
split command, 55, 56, 146 
sprintf command, 50 
SQL 
basics, 159-162 
tables, 159-162 
tdbc, 162-167 
SQL command, 165 
SQLite, 12, 159 
sqliteDB command, 163 
square root, 72 
sscanf, 575 
sscanf function, 52 
stack, 658 
stack class, 245 
stackCmds, 234 
stackDef string, 219, 234 
StandAlone Runtime Kit. See Starkit 
standard dialog widgets, 495-506 
tk_chooseColor, 497-498 
tk_dialog, 502-503 
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standard dialog widgets (continued) 
tk_getOpenFile, 498-500 
tk.getSaveFile, 500-501 
tk_messageBox, 501-502 
tk_optionMenu, 496 
tk_popup, 503-506 
Starkit, 704, 722-724 
language, 722 
primary site, 722 
sdx program, 722-723 
stand-alone, 723 
supported platforms, 722 
tclsh, 722 
unwrapping, 723 
wish, 722 
wrapping, 723 
tarpack, 722-724 
tart angle, 395 
tart argument, 119-120 
tartIndex, 467-468 
tateArray (debugLevel), 741 
tatementCmd, 682-683 
tatements subcommand, 164 
atic methods, 278-279, 310-312 
atic variables, 308-310 
taticVar variables, 214 
tderr, 99 
tdin, 23, 99 
tdout, 99 
tipple bitmap, 394 
tr option, 76 
tring command 
equal, 762 
example, 53-54 
first, 48, 121-122 
is, 50 
last, 48 
length, 48-49 
map, 49, 762 
match, 47, 121-122, 762 
range, 49 
script example/output, 54-55 
specific for tests, 762-763 
tolower, 48 
toupper, 48 
string trimleft command, 753 
stringArg, 183 
strings, 45-47 
bad, 46-47 
conversion to list, 117-118 
evaluating, 188-190 
joining lists into, 147 
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legitimate, 46 
list conversion to, 56 
processing commands, 47-54 
regular expression, 124-133 
splitting into lists, 117-118 
substitution, 187-188 
strod, 575 
strtol, 575 
strtoul, 575 
struct, 152 
struct, saving data in, 154 
style styleType, 395 
subclasses, returns, 298 
subSpec, 130 
subst command, 188 
substitutions, 40—43 
with backlashes, 41-43 
with curly braces, 41-43 
with quotes, 41-43 
of strings, 187-188 
symbols, 36-37 
subwidgets, 508 
superclass command, 280 
superclass methods, 252, 286 
superclasses, 275, 298 
SWIG, 704, 724-726, 727-728 
definition files, 725 
delete_point command, 726 
language, 724 
primary site, 724 
purpose, 724 
script example/output, 726-727 
supported platforms, 724 
syntax, 726 
translatePoint command, 725 
switch command, 8, 75-78 
switch statement, 754-755 
Sybase, 159 
SybTcl extensions, 12 
syslog daemon, 109 
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tableName, 160 

tablePtr, 595 

tables, 161 
columns, 161 
creating, 160, 165 
fields, 160 
naming, 160 
populating, 165 
referenced, 167—175 
rows, 161 


SQL, 159-162 
values, 161 
tables command, 172 
tables subcommand, 164 
tableStrings, 595 
tag taglist, 394 
tagID. first, 452 
tagID. last, 452 
tagOrId, 401, 402 
tags, 391-392, 466-474 
creating, 466-467 
destroying, 466-467 
finding, 467-471 
index ranges, 469 
text widget, 452, 454 
using, 471-474 
tangent, 71 
tar archive, 749-750 
Tel 
argument modification, 753 
array, 156-157 
building from sources, 633-634 
comments, 38 
convention, 35 
data representation, 38-39 
design goal, 2 
documentation, 3—5 
as embeddable interpreter, 11-12 
errors, 40 
exception handling, 80-83 
as extensible interpreter, 11 
as general-purpose interpreter, 8-11 
as glue language, 6-8, 748-754 
input/output in, 99-104 
invoking other programs in, 6 
modularization, 83-86 
modules, 230-231 
numbers in, 752-753 
objects, 197-200 
overview, 2-3 
as rapid development tool, 12-13 
standard distribution, 3 
strengths, 1 
syntax, 36-37 
trees in, 157-159 
uses, 1, 3 
word grouping, 37-38 
Tcl Dev Kit, 703-704 
Tcl Engineering Guide, 247 
Tcl Extension Architecture (TEA), 588-589 
Tcl extension generators, 724-728 
Critcl, 727-728 
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SWIG, 724-726 
| namespace, 214 
1-Obj, 575-576 


Tcl Plugin for Netbeans, 25 
Tcl scripts, 7, 24 


canceling, 385-386 

control structures, 8 

error handling, 7 

evaluating, 25-26 

evaluating, Macintosh, 28-32 
evaluating, UNIX, 26-27 
evaluating, Windows, 27-32 
executable, 137-138 
extraction for unit testing, 743 
GUI support, 7, 8 

interactive evaluation, 23-24 
interactive mode debugging, 739-741 
language consistency, 7 
loading code from, 84-85 
making, 137-138 

math operations, 8 

MS-DOS .bat files vs., 7-8 
program output access, 8 
program output handling, 7 
returning status to, 581-582 
scheduling, 383-385 

string manipulation, 8 

Unix shell scripts vs., 7 


Tcl Style Guide, 39 
Tcl/Tk system 
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GUI support, 10 
internationalization, 10 

Java vs., 10-11 

Perl vs., 9-10 

Python vs., 10 

source code distribution, 633-634 
source code repository, 1 
speed, 10 

syntax, 9 

thread safety, 10 

Visual Basic vs., 9 
-AddError, 606 
-AddErrorInfo, 582, 603 
-AddObjError, 606 
-Add0bjErrorInfo, 582, 603 
-AppendObjTo0bj, 581 
-AppendStringsTo0bj, 581 
L_APPEND_VALUE, 580, 613 
Check, 704 

command line flags support, 709-710 
distribution, 710 

language, 709 
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primary site, 709 

script example/output, 710 
supported platform, 709 
_CmdDeleteProc, 573 
_CmdProc, 572 
-CreateCommand, 573, 574, 577 
-CreateHashEntry, 583 
_CreateInterp, 627-628, 658 
-Create0bjCommand, 574-575, 595 
_-CreateThread, 658, 662 
_DeleteHashEntry, 583 
Eval, 627-628 

Exit, 627-628 
-FindExecutable, 627 
_-FindHashEntry, 583 
-GetDoubleFrom0bj, 577 
GetHashValue, 584 
-GetIndexFrom0bj, 595, 601 
_-GetIntFrom0bj, 577 
-GetStringFrom0bj, 577-578 
GetVar2, 612 


TCL_GLOBAL_ONLY, 580, 612 


-HashEntry, 606 

-HashTable, 582-585 

_Init, 627-628 
-InitHashTable, 583 

-Interp, 572 

xinterp, 574, 579, 582, 612, 613, 619 


_JoinThread, 658, 662 
L_LEAVE_ERR_MSG, 580, 613 


Tellib, 759 


LLIBPATH variable, 230 
L_LIBRARY, 19 
L_LIST_ELEMENT, 580, 613 
L_NAMESPACE_ONLY, 580, 613 
-NewDouble0bj, 578 
-NewInt0bj, 578 
_NewStringObj, 578 

Obj 
data representation, 575 
*objPtr, 579, 580, 581, 582 
returning results, 578 

Tcl list object, 619 

*Tcl ObjSetVar2, 613 
1_0bjCmdProc, 572, 573 
]_O0bjGetVar2, 613 
]_ObjSetVar2, 613 
L_ONE_WORLD_KEYS, 583 


TclOO, 2, 241-242 


callbacks, using with, 305-308 


Tcl CreateInterp command, 627-628 


class, 242-247 
class modification, 268-274, 277-278 
constructor modification, 277-278 
destructor, 245-247 
destructor modification, 277-278 
filters, 260-263 
functionalities, 308-317 
inheritance, 251-260 
inheritance modification, 275-276 
methods, 247-251 
object modification, 280-284 
static methods, 278-279, 310-312 
static variables, 278-279, 308-310 
variable modification, 277-278 
widget and, 335-336 
TclOO widget, 335-336, 550-567, 568 
callbacks, 560-561 
class name as widget type, 557-560 
compound, combining, 561-563 
functionalities, adding, 564-567 
wrapper proc, 551-556 
L_PARSE_PART1, 613 
_pkgPath variable, 136 
_PkgProvide, 595 
_platform variable, 136 
-PosixError, 582 
Prop package, 737 
-SetDouble0bj, 580 
-SetErrorCode, 582, 603 
SetHashValue, 584 
-SetHashValue, 606 
Set Int0bj, 580 
-SetObjErrorCode, 582, 609 
-Set0bjResult, 579 
-SetResult, 579 
SetStringObj, 581 
-SetVar, 595 
SetVar2, 612 
sh interpreter, 2, 17 
as command shell, 22—23 
errors, 19 
exiting, 22 
installing, 17-18 
interactive use, 22—24 
Starkit, 722 
starting, 17-18 
starting, Macintosh, 20-21 
starting, UNIX, 18-19 
starting, Windows, 19-20 
tclsh shell, 751, 752 
TCL_STRING_KEYS, 583 
TclTutor, 35 
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tcl_version variable, 136 tag prevrange, 467-468, 491 


Tc1X extension, 2, 12, 666, 675-679 tag ranges, 469 
features, 676 tag remove, 466, 491 
for_recursive_glob command, 676 tagoff, 458 
language, 675 tagon, 458 
primary sites, 675 text, 458 
purpose, 676 window, 458 


scanfile command, 677 
scanmatch command, 677 
script example/output, 677-679 


window create, 474-478, 491 


text item, 396, 407-410 
text widget, 327, 451-490 


supported platforms, 676 content, 451 

syntax, 676-677 creating, 455-457, 490 

use benefits, 676 deleting text from, 460 
TCP/IP client, 105 images, 455 
tcsh, 19 index descriptions, 453-454 


TDBC package, 159, 666, 679-686 inserting images and widgets into, 474-478, 491 
drivers, 679-680 inserting text into, 458-460, 490-491 


language, 679 
loading, 163 
primary site, 679 


interactive help with, 486-490 
location index, 460-463 
marks, 452, 454, 463-465 


program flow, 162 overview, 451-455 
supported platforms, 679 searching for text within, 460-463 
using, 162-167 subcommands, 458-478 
teleport command, 644 support, 90, 451 
Telnet, 105 tags, 452, 454, 466-474 
test argument, 119-120 text location in, 452-454 
tests directory, 589 window, 455 
text, 160 textName mark subcommand, 463-465 
text textString, 52 


deleting, 458-460 

HTML, displaying, 478-480 
inserting, 458-460 
searching, 460-463, 491 
tags, 466-474 


text command 


delete, 460, 491 

dump, 458 

image, 458 

image create, 474-478, 491 
insert, 458-460, 490-491 
mark, 458 

mark names, 491 

mark previous, 491 

mark set, 463-464, 491 
mark unset, 463, 491 
search, 460-463, 491 

tag add, 466, 491 

tag bind, 471-472, 491 
tag configure, 472-473 
tag delete, 466-467, 491 
tag names, 467-468, 491 
tag nextrange, 467-468, 491 


textvariable command, 335 
thread command 
create, 652-653, 656, 662 
eval, 653, 662 
id, 656 
join, 655 
names, 656 
release, 653, 655 
send, 652-654, 656, 662 
wait, 653 
threaded, 137 
threads, 652-657 
basic actions, 652 
joinable, 653, 655 
operating systems and, 652 
preserving, 653 
TIFF library code, 702 
time calculation, 752-753 
time command, 139, 176, 761 
Tk graphics, 321-387 
basic widgets, 327-328 
button widget, 329-330 


checkbutton widget, 354-355 
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Tk graphics (continued) script example/output, 718-719 
color naming convention, 323 shortTest.tcl script, 717-718 
container widgets, 336-344 stub, 717-718 
dimension conventions, 323-324 k_version variable, 136 
entry widget, 330-333 kwait command, 544-545 
frame widget, 337-338 TOCX extension, 9 
grid layout manager, 351-352 Tool Command Language. See Tcl 
label widget, 328-329 oplevel command, 381 
label frame widget, 339-340 oplevel widget, 328, 336 
listbox widget, 367-371 oplevel window, 506 
menu widget, 356-357 Tower of Hanoi code, 231, 234-236 
namespace in, 333-335 race command, 640, 662 
options, 324-325 evaluating callback with, 306 
options, setting, 325-327 examining variables when accessed with, 737-739 
pack layout manager, 346-351 syntax, 644 
panedwindow widget, 342-344 triggering procedure with, 645-646 
place layout manager, 344-346 traceProc procedure, 737 
radiobutton widget, 353-354 transaction subcommand, 164 
selection widgets, 352-371 translatePoint command, 725 
TclOO in, 335-336 Tree class, 668 
ttk:notebook widget, 340-342 trees, 157-159 
widget layout, 344-352 binary, 157-159 
widget naming conventions, 322-323 in Tcl, 157-159 
widgets, creating, 322-323 trigonometric functions, 71 
tk_chooseColor, 497-498 TSIPP extension, 12 
script output, 497-498 ttk:notebook widget, 336, 340-342 
syntax, 497 creating, 340-341 
tkcon, 23, 743-744 height, 341 
tk_dialog, 502-503 naming, 340 
script example, 503 position, 341 
script example/output, 504-506 script example/output, 341-342 
syntax, 502, 504 syntax, 340-341 
tk_getOpenFile, 498-500 tabs, 341 
options, 498-499 tabs, adding, 341 
script example/output, 499-500 tabs, inserting, 341 
syntax, 498 using, 341 
-getSaveFile, 500 window, 341 
Tk_Init function, 627-628 typeList, 92 
TK_LIBRARY environment variable, 19 types option, 93 


-messageBox, 501-502 
options, 501 


syntax, 501 U 
_optionMenu, 496 uid, 97 
creating, 496 unexport command, 271, 280 
syntax, 496 Unicode, 45 
-popup, 503-506 uniqueNumber namespace, 212, 214, 215-217 
atel, 19 UNIX 
TkTest, 704, 717-721 editors, 25 
author, 717 exiting tclhs/wish, 22 
language, 717 init.tcl location, 226 
primary site, 717 shell scripts, 7 


purpose, 717 starting tcl sh/wish under, 18-19 


tar achive, creating, 749-750 
Tcl script file evaluation under, 26-27 
Tcl/Tk installation, 635 
Tcl vs., 7 
tclsh shell and, 751 
unix directory, 589 
unset command, 191 
unset operation, 737 
update command, 382-383, 387, 754 
uplevel command, 120, 191-192, 308-309, 312 
upper, 50, 128 
uppercase latters, 128 
upvar command, 662 
aggregated objects, 312 
change of scope, 120 
fi leevent command, 642 
global and local scope, 190-191 
tips, 753-754 
trace command, 645 
URLs, searching, 131-133 
use method, 312 
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validatedLabelEntry class, 564-566 
value*, 66 
valueList, 80 
values, grouping, 152-156 
varchar, 160 
variable command, 237, 302 
namespace command, 211-212 
00::def ine command, 277 
0o::0bjdefine command, 280 
TclOO, 243 
variableName, 335 
variables 
argc, 136, 739 
argv, 136, 739 
assigning values to, 44-45 
auto_path global, 226 
bound, 681 
env, 136 
errorCode, 80-83, 136 
errorInfo, 80-83, 136 
global, 135, 136-137, 755-756 
global information, 136-137 
information, 136-137 
in packages, 226 
regexpArgs, 189 
scope, 135-136 
static, 278-279, 308-310 
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staticVar, 214 
TCLLIBPATH, 230 
cl_pkgPath, 136 
cl_platform, 136 
tcl_version, 136 
tk_version, 136 

race command, 737-739 
See also command(s) 
varName, 52, 80, 130, 545, 734 
version number, 228-229 

vi, 25 

vim, 703 

Visual Basic, Tcl/Tk vs., 9 
vwait command, 110 


W 
while command, 8, 40, 79 
while loops, 8 
widgetcget command, 512 
widgetcommand command, 512, 517 
widgetconfigure command, 512 
widgetName command, 325 
widgetNameconfi gure command, 387 
WidgetNameProc procedure, 515 
widgets, 321 
access conventions, 507 
background color, 324 
border width, 324 
button, 327, 329-330, 387 
canvas, 327, 391-448 
changes to, 754 
checkbutton, 327, 354-355 
color naming convention, 323 
container, 336-344 
conventions, 323-324 
creating, 322-323 
dimension conventions, 323-324 
entry, 327, 330-333, 387 
fonts, 324 
frame, 328, 336, 337-338, 387 
frames, 507 
height, 324 
highlight color, 324 
label, 327, 328-329 
label frame, 328, 336, 339-340 
layout, 344-352 
listbox, 327, 367-371 
menu, 327, 356-364 
menubutton, 327, 356-364, 387 
message, 327 
namespaces and, 333-335 
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widgets (continued) winfo command, 428, 433 
naming conventions, 323 wish interpreter, 3, 381 
options, 325-327 errors, 19 
panedwindow, 328, 336, 342-344 exiting, 22 
pull-down menus, 356-367 icon, 21 
radiobutton, 327, 353-354 installing, 17-18 
relief for, 324 interactive use, 22—24 
scale, 328, 379-381, 387 for remote debugging, 747-748 
scrollbar, 328, 372-379 Starkit, 722 
scrolledLB, 512-514 starting, 17-18 
selection, 352-371 starting, Macintosh, 20-21 
spinbox, 328 starting, UNIX, 18-19 
standard dialog, 495-506 starting, Windows, 19-20 
TclOO, 335-336, 550-567 wish script, 6 
ext, 325, 327, 451-490 withTrace class, 307 
_chooseColor, 497-498 wm command, 428 
dialog, 502-503 geometry, 429, 433 
_getOpenFile, 498-500 overridereddirect, 430 
_getSaveFile, 500 pointerxy, 432 
_messageBox, 501-502 protocol, 431 
-optionMenu, 496 wm title command, 382 
oplevel, 328 WordPerfect, 25 
tk:notebook, 336, 340-342 words, 128 
width, 325 grouping, 38-39 
width width, 394 size, 137 
win directory, 589 write operation, 737 
windowName, 452, 545 
windows 
background color, 381 X 


binding, 647 


border width, 381 X-Bitmap file, 438-439 


creating, 381-382 eee Ceeae HOi 

height, 381 ry ee 
XOTel, 241 

name, 381 

relief for, 381 

script example/output, 38 1-382 

text widget, 455 Z 

top-level, 381-382 zip archive, creating, 750 


width, 381 zsh, 19 


